Pijul man pages


#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?


#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.