Re: [request for review] Port of s6 documentation to mdoc(7)

[Alexis <flexibeast@gmail.com>]

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

> This is clearly the most advanced conversion ever
> performed, well done!

Thank you!

> Would you be willing to add a small Makefile that by default 
> invokes
> the mandoc commands to produce the formatted man pages, and with 
> an
> install target that installs the source to $(MANDIR), by default
> /usr/share/man ? I would then be able to review them. Thanks :)

Certainly. i'll do that once i've completed a linting pass.

> (AS you're aware if you've been here a while, I don't read mdoc 
> source,
> and I will. not. learn. it.)

Heh, fair enough. :-)

> Would you be willing to maintain that repository
> for when I make changes to the s6 documentation? Changes should 
> be few
> and far between, except for fixes and new feature additions 
> (which I
> don't think there will be much of). If so, I would gladly add a 
> link to
> that repository in the official s6 home page, for people who, 
> like you,
> prefer man pages.

Sure, i'd be happy to reflect any changes.

> I'd hold off on s6-rc for now,
> because I'm in the process of exploring a possible redesign (for 
> better
> integration of features that distributions want before packaging 
> and
> using s6-rc), so it's not improbable that all the documentation 
> gets
> rewritten in a not-too-distant future.

Ah, okay - thanks for the heads-up.

> What kind of changes to the text? if it's just the text of the 
> link,
> such as changing the name of a package to the full URL of the 
> package,
> then please go ahead and do what is needed. But relevant links 
> in
> SEE ALSO works too.

Now that i think about it some more, maybe i could simply put the 
link in parentheses? For example, with:

    a CDB file cdbfile then exits 0.

where "CDB file" is a link to the relevant Wikipedia page, the 
mdoc would produce output like:

    a CDB file (http://en.wikipedia.org/wiki/Cdb_(software)) 
    cdbfile then exits 0.

Similarly,

    lines with a TAI64N timestamp and a space.

would become:

    lines with a TAI64N timestamp 
    (http://skarnet.org/software/skalibs/libstddjb/tai.html#timestamp) 
    and a space.

At any rate, i think it might be a good idea for such links to be 
mentioned in "SEE ALSO" regardless.

> If there are other typos or grammatical errors you've noticed, 
> please
> send them to me (maybe privately in order not to spam the list) 
> and I'll
> fix them. If the fixes need more explanation and interactive 
> dialogue,
> hop on #s6 some time during the week to discuss them. :)

*nod* i'll try to put together an email with the relevant 
 information, and start hanging out on #s6. :-) i'm usually on 
 Freenode,  in #voidlinux in particular, but not necessarily 
 active at the same time as others - i'm in Melbourne.au.

>  Fixed in the latest git head, thanks!

:-D


Alexis.