2024-08-08 Man pages
====================

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 ​#Software #Documentation
​#Documentation

2024-08-09. At one point I was interested in using troff as an
alternative to LaTeX, so not to write documentation but to create
PDFs, and I kept eyeing the mom macros. But before I could give them
a try I discovered how to create PDFs using Markdown to HTML to PDF
via weasyprint and that has been my workflow ever since. For a zine
I’m contributing to, however, I’m using groff and the ms macros
because that’s what’s in the Makefile…

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.