Here's a great thing on the command line. You want to use the command **foo** and don't know how, so you run **man foo** and read the manual page. Sometimes there will be more info in different "sections". Commands are in section 1, which is why documentation would sometimes refer to the command "foo" as **foo(1)** because **foo(5)** might document the file format or the config file that goes along with the command.
If that's news to you, run **man man**. And if you find the structure bewildering, read the manual on how to write manual pages: **man man-pages** (section 7).
I've embraced man pages because when I write Perl code, I can put documentation into the script such that when the script is installed, it automatically works as its own man page – this works for jupiter, bookmark-feed – it also works for bigger projects, like phoebe where each extension is also a Perl module and therefore also gets its own man page.
For programming languages where the documentation is more focused on documenting the code, things are different. Of course, there's `pydoc` for Python code and `go doc` for Go code, but it's not great. The list of variables and functions are maybe suitable for libraries, but not for applications.
Since I don't enjoy writing man pages directly (`man` is actually a macro package for the `nroff` language, see **man nroff**, obviously) I write my documentation in the scdoc format. @drewdevault@fosstodon.org wrote it in 2018. It looks a bit like Markdown and friends and I like it. I even put a little sequence of `sed` expressions into a Makefile to turn scdoc into Markdown so that I could publish the man pages on this site, see Oddµ man pages.
When documentation for a project is a website, I wonder how they serve people offline or with bad connections. Perhaps they want to write the documentation in texinfo? I haven’t done that in a long time but I really enjoy reading a well-written manual like that. And you can get a PDF for free but I’m not sure anybody really wants that. Even a README is bad because in those rare cases where the program gets added to a distro, how will end-users find the README? Man pages are the answer.
README files and offline copies of the HTML documentation have multiple problems: Which directory is it, exactly? `/usr/doc` does not exist on my system. `/usr/share` lists lots of package names but these are not the docs. `/usr/share/doc` is the one! But the problems continue. Which of the directories do you check? Sometimes you're looking at binary and it's also not obvious what the package name would be. `find` is in `/usr/share/doc/findutils`, for example. And we're still not done. Which is the file that you want to read when you're faced with `BUGS changelog.Debian.gz changelog.gz copyright README README.Debian README.frames RELEASE-NOTES.txt WhatsNew.gz` – it's README, I guess, but I am always confused. It's all very confusing.
Compared to this, man pages are so much better.
And some package managers like `go`, `pip` (Python), `cabal` (Haskell) and `cargo` (Rust) don’t install any of these files, I think.
I suspect that many developers consider using a website like Read the Docs to be good enough. Bad luck for people who are offline or who have bad reception, in hotel rooms with bad wifi, in planes, in trains? My sister lives in the Rhine valley, on the German side, close to Switzerland, in a tiny village of a bit more than 100 people. They have no glass fibre. They have bad reception, both from Switzerland and from Germany. It's terrible! But even for me: I have wifi in the apartment and glass windows that act that block the signal. I have no reception on the balcony unless I use my phone as a hotspot.
Local documentation that is easy to find is so much better.
And man pages are powerful. *All* of Perl is documented in many pages. All the modules. All the switches. All the language features. I learned to program in Perl from man pages back when my browser was NCSA Mosaic. (I am a bit astonished to find that I still knew that acronym! But I didn’t know that it stands for National Center for Supercomputing Applications.) Anyway, what I wanted to say is that man pages can be used to document large and complex things. From the command line, they are readily accessible. With the right man reader, they can act as a hypertext, linking to other pages. They don’t have to be terse and cryptic, either. Man pages can be tutorials, introductions, FAQs, and more. And if you write man pages using a suitable format, you can still generate HTML pages with links.
If you're not writing man pages, if your community doesn't have the habit of writing man pages, start small. Get `scdoc` and write a little something. Skim **man man-pages** and learn about the conventions, then write some text files. Then use `scdoc < text-file > man-page` to create the file and install them into `~/.local/share/man`, following the conventions. A page from section 1 (commands) has the extension ".1" and goes into `~/.local/share/man/man1` whereas a page from section 5 (file formats and config files) has the extension ".5" and goes into `~/.local/share/man/man5`.
#Programming #Software #Documentation
using troff as an alternative to LaTeX
create PDFs using Markdown to HTML to PDF
The reason I write this all up is that flexibeast wrote in, saying that man pages can be written using the semantics-oriented mdoc macros instead of the presentation-oriented man macros – and they had written an mdoc quickstart guide. Nice!
I really have to take a look at mandoc as a groff alternative.