Re: s6-man-pages update
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
Laurent Bercot 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
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
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
Laurent Bercot 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
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
