Re: [groff] groff as the basis for comprehensive documentation?
Thanks, Ingo, for that very informative reply. I did just start reading the mdoc man page after sending that mail. Thanks for the additional resources. I shall check them out as I continue on with this aspect of the project. - Nate -- "The optimist proclaims that we live in the best of all possible worlds. The pessimist fears this is true." Web: http://www.n0nb.us GPG key: D55A8819 GitHub: N0NB signature.asc Description: PGP signature
Re: [groff] groff as the basis for comprehensive documentation?
Hi Nate, Nate Bargmann wrote on Sun, Apr 15, 2018 at 04:17:59PM -0500: > I have long been involved with a project that has lacked good > documentation for nearly all of its existence. We've had documentation, > but it isn't in a good format for generating man, HTML, or PDF versions. [...] > After letting this sit for some time, I realized that I had not > investigated groff deeply That is really strange. :) It has always been the central format for research and commercial UNIX, it has always been used by all the BSD projects (actually using GNU troff for about two decades), and the Linux man pages project also uses it, so i would consider it the canonical solution for documentation in general. > But (there is always a 'but'), beyond the collection of nroff files I am > creating for the man pages, it would be nice to be able to tie them all > together into a whole. For rendering manual pages, consider using mandoc(1) rather than groff. While it is not a typesetting system and consequently has *much* weaker PostScript and PDF output than groff, it is slightly better for terminal output and **much** better for HTML output. The input languages are exactly the same, it is merely a different parser and formatter implementation strictly optimized for manual pages. Also, both the command line and CGI tools are *much* more powerful than the combination of groff with man-db, or with any other man(1) implementation that runs on Linux. Specifically, for the question you are asking, make sure you have the man(1) implementation from the mandoc toolkit installed, then use $ man -aks 2 ~. to view a combined document containing all the section 2 manual pages on a terminal or $ man -T pdf -aks 2 ~. > tmp.pdf to create a single PDF document containing them all, or https://man.openbsd.org/?query=~.&apropos=1&sec=2 for an online HTML / CGI version with hyperlinks; off course, you can also create a hyperlinked offline HTML version, for example with the catman(8) tool contained in the mandoc toolkit, but the online version is certainly more useful. All that is available out of the box, without installing any packages whatsoever, on OpenBSD, Alpine Linux, and Void Linux. FreeBSD, NetBSD, and illumos also contain all the required binaries by default without installing any package, but they install less powerful implementations of man(1) by default, but you can easily symlink mandoc to man to get the mandoc implementation of man(1). Debian, Ubuntu, Arch, Gentoo, Slackware, Homebrew, MacPorts, and pkgsrc provide packages that you can install. Building from source is also tested on AIX and Solaris 9-11. > I was hoping the mom macro package might have some sort of a facility > for this idea, While mom is certainly a very considerable option for a wide range of non-manual-page documents, it cannot be used with manual pages at all. But there is no need, mandoc already provides all you are asking for, and more - for example, building a PDF document on demand containing the pages returned by a specific semantic search query - no matter whether the query returns a handful, dozens, or hundreds of pages. > Regardless, I plan to continue with improving our project's collection > of man pages and work from there and will likely remove the Texinfo > files at some point. Sounds like a reasonable plan - http://mandoc.bsd.lv/texi2mdoc/ may or may not help with the transition, by the way. It is not very actively maintained these days (though i might fix bugs in it if any are reported), and the output certainly needs manual postprocessing, but using it is very likely to save you quite some work compared to writing everything from scratch. Of course, make sure to use the semantic mdoc(7) language, not the old, purely presentational man(7) language, or you won't have semantic searching, and most of the hyperlinking won't be present, either. Also, writing man(7) is much harder than writing mdoc(7). For documentation, see http://mandoc.bsd.lv/ For overviews of the wide variety of topics that are being worked on regarding roff(7) as documentation format, see https://www.openbsd.org/papers/eurobsdcon2015-mandoc.pdf https://www.bsdcan.org/2018/schedule/events/958.en.html Yours, Ingo
[groff] groff as the basis for comprehensive documentation?
I have long been involved with a project that has lacked good documentation for nearly all of its existence. We've had documentation, but it isn't in a good format for generating man, HTML, or PDF versions. Long ago I started with Docbook and then that got to a point no one else would touch it and I didn't want to either. XML was the "wave of the future" but I didn't jump on that wagon. The project has long had the capability of using Doxygen and I find its output wanting and never warmed up to it as even with it, other man pages needed to be maintained and its man output is horrid. Some years ago I moved over to Texinfo and while we get nice info, HTML, and possibly PDF files from the document source, there are no man pages and I don't wish to maintain two sets of documentation, which is the same road I found myself on with Docbook. After letting this sit for some time, I realized that I had not investigated groff deeply and now having made myself more familiar with it and its macro packages, I still have some questions. Despite all the offered solutions, I still find "man " to be the fastest and easiest way to look at reference material. The groff tools to render individual pages into HTML and PDF do a very nice job. Thank you. But (there is always a 'but'), beyond the collection of nroff files I am creating for the man pages, it would be nice to be able to tie them all together into a whole. Or, rather a master document, likely in man7, that when rendered as HTML has links to the reference pages also rendered as HTML. When rendered as PDF, the reference pages rendered as PDF could be collated into a single PDF document. I was hoping the mom macro package might have some sort of a facility for this idea, but its inclusion only seems to be other mom formatted files. In fact, it seems as though all of the macro packages are mutually exclusive. Perhaps I have not looked deeply enough. Regardless, I plan to continue with improving our project's collection of man pages and work from there and will likely remove the Texinfo files at some point. Thanks, - Nate -- "The optimist proclaims that we live in the best of all possible worlds. The pessimist fears this is true." Web: http://www.n0nb.us GPG key: D55A8819 GitHub: N0NB signature.asc Description: PGP signature
[groff] [Utroff] Utmac ported to neatroff
Hello alls, I am pleased to announce you that my macro set Utmac has been ported to Neatroff. And indeed, I must admit it is a pleasure to work with Neatroff! For years, I was using Heirloom Troff, for its ability to format paragraphs at once. Neatroff does that too, in a much more transparent manner. To switch from Heirloom to Neatroff, all I had to do was removing Heirloom's specifities and complexity. As a result, the code of Utmac is now much simpler, and close to be Groff compatible. As a side effect (which could interest Groff users), since Neatroff does not implement nroff, Utmac is using `groff -Tutf8` to format plain text files, as follow: $ groff -k -Tutf8 -mum f.tr > f.man $ groff -k -Tutf8 -mut f.tr > f.txt $ groff -k -Tutf8 -muw f.tr > f.mkd $ groff -k -Tutf8 -mux f.tr | postxml > f.xml There are probably still bugs here and there, but for the most part it works well, as can attest the Utroff html pages (http://utroff.org), and the manual pages shipped in all Utroff archives. I would like to be able to share some of my enthusiasm for Neatroff. It is a wonderful troff implementation, not only for its paragraph at once and right-to-left scriptures implementations, but also because its source code is clear, and its installation easy. Ali Gholami Rudi is helpful and attentive, which is a precious thing too. People willing to have a look at Utmac can find it here: https://github.com/pjfichet/utmac And Neatroff is there: http://litcave.rudi.ir Kind Regards, Pierre-Jean.
