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 > GNUnet-developers@gnu.org > https://lists.gnu.org/mailman/listinfo/gnunet-developers > _______________________________________________ GNUnet-developers mailing list GNUnet-developers@gnu.org https://lists.gnu.org/mailman/listinfo/gnunet-developers