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

[Florian Dold]

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
2. indices and a table of contents
3. easy navigation to other parts of the document (sidebar or
next/prev/top links)
4. the ability to include images (I disagree that our documentation is
somehow "not a real book" and should not include them)

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.

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.

- 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
>