s6-man-pages update

s6-man-pages update

[Alexis]

Hi again all,

i've now completed the linting pass for the s6 man pages. The few 
remaining lint issues are either commented in the sources, or 
aren't actually an issue in this context.

As per Laurent's request, i've also added a Makefile to facilitate 
installation; details in the repo README:

    https://github.com/flexibeast/s6-man-pages/

The main thing still left to do is work out how to deal with 
certain types of links.

Laurent, you wrote:

> I think  that solely depends on  the number of such  links. If 
> there
> are just a few,  it's fine. If there are a lot of  links in a 
> page, it
> would make  reading pretty unwieldy. Because  I think there are 
> a few
> pages with too many links, maybe it would be best, for 
> consistency, to
> just use footnotes?
>
> < a CDB file[1] cdbfile then exits 0.
> <
> < (...)
> <
> < SEE ALSO
> <
> < [1]: http://en.wikipedia.org/wiki/Cdb_(software)
>
> Maybe mdoc even has a mechanism for footnotes? I don't know.

As far as i'm aware, mdoc has no built-in mechanism for footnotes 
(certainly the word isn't used in the mdoc(7) man page).

Most of the links in the man pages are cross-references to other 
pages in the s6-man-pages collection, so they're already handled 
by the Xr macro. The remaining links aren't particularly numerous, 
and can basically be divided into two groups:

* links to other skarnet.org documentation which does not yet have 
  man pages: s6-networking (s6-tcpserver-access, s6-tcpserver, 
  s6-tcpserver4, s6-tcpserver6), execline (execline and execlineb, 
  maybe others as well?), and skalibs stuff. For an example of a 
  page referring to s6-networking software, 
  cf. s6-connlimit.1.in. If that documentation was available as 
  man pages, these could just be made cross-references too. 

* links to non-skarnet.org sites, such as djb's site. These 
  certainly seem amenable to use of the footnoting style you 
  described above.


Alexis.

Re: s6-man-pages update

[Laurent Bercot]

>i've now completed the linting pass for the s6 man pages. The few remaining lint issues are either commented in the sources, or aren't actually an issue in this context.
>
>As per Laurent's request, i've also added a Makefile to facilitate installation; details in the repo README:
>
>https://github.com/flexibeast/s6-man-pages/

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

  Two comments:
  - 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.
  - You should list yourself in the AUTHORS section: I wrote the content,
but you wrote the man pages.


>* links to other skarnet.org documentation which does not yet have  man pages: s6-networking (s6-tcpserver-access, s6-tcpserver,  s6-tcpserver4, s6-tcpserver6), execline (execline and execlineb,  maybe others as well?), and skalibs stuff. For an example of a  page referring to s6-networking software,  cf. s6-connlimit.1.in. If that documentation was available as  man pages, these could just be made cross-references too.

  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"? That would be ideal for placeholders
until the documentation for other packages is ported (which may very
well be "never").


>* links to non-skarnet.org sites, such as djb's site. These  certainly seem amenable to use of the footnoting style you  described above.

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

--
  Laurent

Re: s6-man-pages update

[Alexis]

Laurent Bercot <ska-supervision@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.

Re: s6-man-pages update

[Érico Nogueira]

On Wed Sep 9, 2020 at 5:19 AM -03, Laurent Bercot wrote:
> >i've now completed the linting pass for the s6 man pages. The few remaining lint issues are either commented in the sources, or aren't actually an issue in this context.
> >
> >As per Laurent's request, i've also added a Makefile to facilitate installation; details in the repo README:
> >
> >https://github.com/flexibeast/s6-man-pages/
>
> Nice work! If you feel they're ready enough, I can add a link to them
> in the s6 main page right away.

Do you think it would make sense to include the man pages in tarball
releases of s6 software? It would help with packaging efforts across
distros, I think. Only downside would be that, since you dislike the mdoc
format, any changes to the man pages would have to be coordinated and
finished by others before you made a release, if the plan is to keep
everything consistent.

Re: s6-man-pages update

[Laurent Bercot]

>Do you think it would make sense to include the man pages in tarball
>releases of s6 software? It would help with packaging efforts across
>distros, I think. Only downside would be that, since you dislike the mdoc
>format, any changes to the man pages would have to be coordinated and
>finished by others before you made a release, if the plan is to keep
>everything consistent.

  That downside is simply too big, and also, I don't want to take
responsibility in the official tarballs for content that I don't audit
myself. I don't think it would be a good trade-off, even for users.
(And that does not mean I don't trust Alexis, or other people in the
community, to do good work! If I didn't, we wouldn't even be talking
about this.)

  What limits packaging efforts across distros is not the number of
packages or where and how to find them; if a distribution has a link
to get the man pages source, they will use it and will just be happy
that there are man pages. What limits packaging efforts, currently, is
only the willingness of distributions to understand and use s6.

--
  Laurent

Re: s6-man-pages update

[Alexis]

Laurent Bercot <ska-supervision@skarnet.org> writes:

>  That downside is simply too big, and also, I don't want to take
> responsibility in the official tarballs for content that I don't 
> audit
> myself ...  if a distribution has a link
> to get the man pages source, they will use it and will just be 
> happy
> that there are man pages.

Fair enough. :-) My thought is, to help distros with packaging, i 
can add tags to the s6-man-pages repo to match the corresponding 
s6 version on which they were based. So at the completion of this 
current process, i could add a 2.9.2.0 tag (assuming that the 
current docs on skarnet.org are from the 2.9.2.0 release). Does 
that sound reasonable?

(i can put together a package template for Void.)


Alexis.

Re: s6-man-pages update

[Laurent Bercot]

>Fair enough. :-) My thought is, to help distros with packaging, i can add tags to the s6-man-pages repo to match the corresponding s6 version on which they were based. So at the completion of this current process, i could add a 2.9.2.0 tag (assuming that the current docs on skarnet.org are from the 2.9.2.0 release). Does that sound reasonable?

  The docs on the website are updated at least at every release, but also
a bit more often: when I have fixes for the documentation, I add them to
the git repo and also to the website. So the website always has the most
up-to-date documentation (barring functionality that has not been
released yet).
  For instance, the current git head, as well as the website docs,
include the fixes to the typos you reported, whereas the v2.9.2.0 git
tag does not include them.

  So I don't know what policy would be best. It would probably be easier
for you to mimic the tags; I can commit to notifying you on git changes
impacting documentation, so you can have a "current" branch mimicking
the state-of-the-art. But it's really up to you, and all in all I think
tags are a good idea. :)

--
  Laurent