gnunet-developers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[GNUnet-developers] proposal: changes to documentation


From: Nils Gillmann
Subject: [GNUnet-developers] proposal: changes to documentation
Date: Sat, 15 Sep 2018 22:48:52 +0000

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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]