Re: s6-man-pages update

From: Alexis <flexibeast_at_gmail.com>
Date: Wed, 09 Sep 2020 23:12:59 +1000

Laurent Bercot <ska-supervision_at_skarnet.org> writes:

> Nice work! If you feel they're ready enough, I can add a link
> to them
> in the s6 main page right away.

Mm, thanks, but i think i'd prefer to wait until i've handled the
link issue. :-)

> - The skarnet.org site is accessible in https, and is
> preferred.
> Intra-site links have no default protocol, so they will link in
> http
> if the client uses http, and in https if the client uses https;
> but
> for absolute URLS, it would probably be best to write them as
> https

Sure, will do.

> - You should list yourself in the AUTHORS section: I wrote the
> content,
> but you wrote the man pages.

Okay, i'll mention myself as the porter.

> I don't want to be making suggestions on work I'm not going to
> do
> myself and that I have no deep understanding of; but is there a
> way to
> have an alternative in .Xr, as in "print as a cross-ref if the
> man
> page exists, else print that text"?

No, Xr only takes a manual name and section number as arguments.

> That would be ideal for placeholders
> until the documentation for other packages is ported (which may
> very
> well be "never").

Well, i'm willing to port the s6-networking and execline docs,
unless the longer-term plan is to convert them to e.g. scdoc,
since (having now looked into it) it's a very weak markup format
that can't represent most of the semantic markup i'd be adding,
including cross-references. No point doing work that is just going
to be removed. :-)

That said, for now i'll follow the footnote-style approach you
suggested more generally, with numbered links to s6-networking and
execline programs in the SEE ALSO section, and the appropriate
number being mentioned inline. If/when the relevant man pages
become available, conversion to use of Xr can be automated.

> Yes, I don't think it's reasonable to expect the whole Web to
> be
> converted to man pages. ;)

*laugh* Indeed!


Alexis.
Received on Wed Sep 09 2020 - 13:12:59 UTC

This archive was generated by hypermail 2.3.0 : Sun May 09 2021 - 19:44:19 UTC