Pijul man pages

Documentation
1

I just wrote the first man page of my life. The language is terrible, but at least the rendering is pretty good.

I think now is a good time to start thinking about a “Pijul Manual”. The man pages are important to write because being able to write something as man pijul-<subcommand> would be awesome and wanted by end-users. But the language is… meh.

Any feedback about the manpage-writing process? Ideas on tools to use?

1 Like
2

Great! Apparently pandoc can convert markdown to man pages (with the -t man option). I’ve never tried it, though…

Also, it might be nice to display the man pages when someone types, e.g., pijul help init or pijul init --help. Git, hg, and darcs all do some version of this (git and darcs seem to use pagers by default, while hg doesn’t), so there’s precedent.

3

I love the idea, but I do not know if rust has a crate to do that yet.

4

Yeah, that part can definitely wait. Having man pages at all is definitely more important, so thanks for getting started!

5

Thanks (:

It shoudn’t be too hard to write quick yet usefull man pages for the most used commands. Also, documenting the configuration file could be useful.

6

Have you thought about going the git way of using asciidoc as the input language and generating man pages, html and info documents from there. I admit, it takes creating some build infrastructure at first (Windows support might be a show stopper) but is extremely lightweight on the side of actually writing documentation.

And making it easy to write new documentation seems to be a lot more worthwhile than having a lean build system.

7

Thanks for the tip. I will have a look into it. We really need some easy to write/easy to access documentation now that pijul becomes more and more usable.

8

I just stumbled upon rust-rst, which uses reStructuredText instead of asciidoc. Might be worth a look, too.

9

The current draft of the manual uses markdown (and even common mark), and mdbook to generate nice webpages.

It doesn’t generate man pages, but I would bet this is already implemented, or at least reasonably easy to do.

10

It doesn’t look like it but just generating HTML. Having docbook as an intermediate format would have the benefit of being able to generate various output formats with standard tools.