Re: [GNUnet-developers] proposal: changes to documentation

[Nils Gillmann]

Florian Dold transcribed 6.9K bytes:
> I'm not the biggest fan of texinfo either, but it works.
> 
> mandoc looks like a terrible replacement, and I strongly disagree with
> your proposal of switching to it.
> 
> When comparing the documentation of mandoc/mdoc
> 
>   http://mandoc.bsd.lv/man/mandoc.1.html
>   http://mandoc.bsd.lv/mdoc/
> 
> to GNUnet or even the parts of GNU Taler documented in Sphinx (only used
> for HTTP API docs)
> 
>   https://docs.gnunet.org/
>   https://docs.taler.net/api/index.html
> 
> there are several crucial things missing in mandoc, just off the top of
> my head:
> 
> 1. cross-referencing inside a document

This is possible, see mdoc(7):

 Sections and cross references
 Sh               section header (one line)
 Ss               subsection header (one line)
 Sx               internal cross reference to a section or subsection
 Xr               cross reference to another manual page: name section
 Pp, Lp           start a text paragraph (no arguments)

iirc when you convert to html Xr will be a link, or could easily be
adjusted with just a bit of sed.

> 2. indices and a table of contents
> 3. easy navigation to other parts of the document (sidebar or
> next/prev/top links)

2 and 3 are only relevant to html and pdf. In the terminal, when
I want to navigate a document I use a pager and its search function.
If I get a page with an overview (like perl(1)) that is good
enough or even a READ MORE section. I see the names and can
type in the pages names. There's even Xman.

Coming back to sed: we could probably just insert those jumps and
links with sed.

> 4. the ability to include images (I disagree that our documentation is
> somehow "not a real book" and should not include them)

We wanted to include the documentation with the software because
it should be available on systems afterwards, even headless ones.
We don't really have a writing style which can include images,
and including images is not so trivial in texinfo (so there will
be questions raised which the documentation of texinfo can't
answer).

> Long-form manuals are not really what man pages are for.
> 
> There are some other reasonable alternatives to texinfo that are widely
> used, such as Sphinx or gitbook, but I don't really see the benefit of
> switching to them, and neither of them supports viewing docs on a
> terminal nor has great output for printing.  Sphinx can actually
> generate texinfo as output, so in theory it has all the same benefits,
> but some people don't like the markdown-like syntax.
> 
> The tools for texinfo are widely available, arch doesn't even have a
> package for mandoc.

I would not want any of those above as they increase the dependencies
even more than texinfo.

man-db (also known as "man") has no problems displaying these pages.

> If build failures caused by the docs are really a problem, then there
> are other solutions, such as telling the build system to just warn if
> docs can't be built.  For Taler, we also have a separate BB worker that
> just builds the documentation and sends out emails if something is wrong
> there.  As you said, it's certainly also possible to commit syntax
> errors in mandoc.

Texinfo causes a syntax error to be an error and fails the build as it
needs to be build, mandoc does nothing by default as it does not need
to be build.

If we turn off documentation by default and make it an opt-in, which
would disrupt less builds with wrong texinfo syntax, we would no
longer include the documentation by default. OF course we could also
make it conditional if and only if texinfo is detected build it.

texinfo and most (all? didn't refresh my memory) other writing systems
you mentioned have a comparable huge dependency and/or compile/runtime
chain. Texinfo usually brings in at least 2 GB - you turn it off, now
you have to read online documentation or get the documentation
elsewhere.

> - Florian
> 
> On 9/16/18 12:48 AM, Nils Gillmann wrote:
> > Hi all,
> > 
> > I have a proposal. If this in rough shape or you have questions, ask.
> > 
> > Roughly: I propose to switch to mandoc for gnunet + gnunet-c-tutorial.
> > This will improve handling of the documentation, impact it has on
> > the project and (most importantly) give a better user experience.
> > I think this change will get more documentation contributions in a
> > safer way.
> > 
> > The Texinfo language has more grammar and more options and traps
> > (than mandoc). In addition to knowing the grammar, you need to install
> > Texinfo/Makeinfo to work with it. A point I liked about Texinfo was
> > the ability to include images. Now I think we should aim for less -
> > images are obviously left for real books.
> > 
> > The content of our documentation follows a scheme which can be covered
> > by everything mdoc has. It has been mostly myself writing
> > this.. occasional help from others and people active in other gnu
> > projects. sometimes I had to tell people where to start with
> > texinfo. and others I had to simply fix. the point of the whole
> > HTML->LaTeX->Texinfo conversion was to make it easier to access
> > documentation AND easier to write. What we do now is regularly break
> > master because people write Texinfo mistakes.
> > 
> > We get the occasional reports. and people rarely(?) react to them -
> > at all or do not notice it - and often do not fix their mistakes. I've been
> > cleaning up and responding to the reports for some time. If something
> > breaks because of documentation, it's also directed at myself first.
> > It's my chosen responsibility to care for the documentation, and my
> > impression is that mandoc/mdoc will be less difficult to handle (than
> > Texinfo) for everyone.
> > A mistake in a mandoc page results in no failure at build, configure
> > or whatever time.
> > Mistakes will still happen, but they will not break the build, they
> > will not interrupt the work of everyone working on gnunet.
> > 
> > What about the outputs we need for online view?
> >> pdf output, (static) html output (and more) are covered:
> >> check 'man mandoc':
> >>
> >> mandoc(1):
> >> ......
> >>      -T output
> >>              Select the output format.  Supported values for the output
> >>              argument are ascii, html, the default of locale, man, 
> >> markdown,
> >>              pdf, ps, tree, and utf8.
> > 
> >>              The special -T lint mode only parses the input and produces no
> >>              output.  It implies -W all and redirects parser messages, 
> >> which
> >>              usually appear on standard error output, to standard output.
> >> ......
> > 
> > what about style?
> >> but it looks less appealing, no idea how much you can style debman
> >> (debian online manpages), archlinux online manpages, and at least
> >> openbsd and others have examples.
> > 
> > this requires to organize the manual differently, which is what I've
> > already started to do for my own project.
> > 
> > What about additional software to install?
> >> You probably have mandoc available on debian systems (since they use
> >> it for debiman).  Some GNU/Linux based systems use it as their
> >> default (Archlinux, Void Linux,.. iirc).  For the display and
> >> editing (as contributors) you could get away with man-db. A minimal
> >> subset of groff is implemented to make groff happy.
> >>
> >> On the dependency level this means we stop imposing texinfo and its
> >> rather large dependency chain for texinfo/makeinfo/texi2(pdf,html)
> >> on potential contributors to the documentation. I write this because
> >> Texinfo requires Texlive at runtime which is hard on some systems
> >> due to its default monolithic size. The systems where it is served
> >> in smaller pieces have figured out a way to do so against upstream.
> >> So I'd really like to say: Want to get started writing documentation?
> >> Just write. You need a reference of the grammar? 'man mdoc' or find
> >> it online.
> >> Okay, now you want to see the results in html or pdf?
> >> I have good news: mandoc depends on zlib and a C compiler. You
> >> might already have it.
> > 
> > What about generating the online formats?
> >> Since we started using / are moving to GuixSD, this would also mean
> >> that I can send my mandoc package to Guix or set up a repository we
> >> can pull from.
> > 
> > Who will do this?
> >> The majority of work if we move to this format can be achieved with
> >> the software I have available. No one else has to do this, I'm
> >> proposing this and I am executing this. I can get a good conversion
> >> with texi2mdoc, followed by manual work and adjustments.
> > 
> > Wrapping it up: I don't want to write pages as small as the help2man
> > dump^excuses we have out there. The manual is long, but I intend to
> > not reduce it too much in size.
> > Furthermore I will add a 'gnunet' page in the section 1 which acts
> > similar to perl(1), which is (among other things) to point out where
> > to go from there.
> > 
> > Side note: Prior to Guix, I can't remember that I ever looked at an
> > info manual. I always used man. This is not just my experience, but
> > a reoccuring one I hear from many people. Sometimes they don't even
> > know info.
> > 
> > Further Reading:
> >> https://www.youtube.com/watch?v=N26pBxJPMxs
> >> https://mandoc.bsd.lv/
> >> https://mandoc.bsd.lv/man/mdoc.7.html
> > 
> > _______________________________________________
> > GNUnet-developers mailing list
> > address@hidden
> > https://lists.gnu.org/mailman/listinfo/gnunet-developers
> >