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

[Christian Grothoff]

Hi Nils,

(1) our handbooks should be "real" books. For example, the GNU
libmicrohttpd manual can even be ordered in print. We should strive for
our documentation to be of book quality.

(2) Texinfo is the offical documentation standard for the GNU project.
Alone for the sake of keeping all things GNU uniform (we're building the
GNU operating system!), we _will_ stick to Texinfo unless the GNU
project decides to switch to a different documentation standard.

As for build issues with the documentation not being addressed nicely /
in a timely fashion, the answer should be to get our CI to notify
committers via e-mail when they break something.

Happy hacking!

Christian

On 09/16/2018 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
>

signature.asc
Description: OpenPGP digital signature