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

From: Alexis <flexibeast_at_gmail.com>
Date: Mon, 31 Aug 2020 17:01:34 +1000

Laurent Bercot <ska-supervision_at_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.
Received on Mon Aug 31 2020 - 07:01:34 UTC

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