# Pijul man pages

**URL:** <https://discourse.pijul.org/t/pijul-man-pages/26>\
**Category:** Documentation\
**Created:** [June 2, 2017, 1:45pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26 "2017-06-02T13:45:54Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![lthms](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/lthms/32/124_2.png) [@lthms](https://discourse.pijul.org/u/lthms)\
**Post date:** [June 2, 2017, 1:45pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26/1 "2017-06-02T13:45:54Z")

</div>

I just wrote [the first man page of my life](https://nest.pijul.com/lthms/pijul:showdeps/86ac2902f045bbe608). 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?

---

<div class="post-metadata">

**Author:** ![joeneeman](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/joeneeman/32/77_2.png) [@joeneeman](https://discourse.pijul.org/u/joeneeman)\
**Post date:** [June 2, 2017, 3:02pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26/2 "2017-06-02T15:02:00Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![lthms](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/lthms/32/124_2.png) [@lthms](https://discourse.pijul.org/u/lthms)\
**Post date:** [June 2, 2017, 3:13pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26/3 "2017-06-02T15:13:06Z")

</div>

> [@joeneeman](#):
>
> 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.

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

---

<div class="post-metadata">

**Author:** ![joeneeman](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/joeneeman/32/77_2.png) [@joeneeman](https://discourse.pijul.org/u/joeneeman)\
**Post date:** [June 2, 2017, 3:38pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26/4 "2017-06-02T15:38:06Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![lthms](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/lthms/32/124_2.png) [@lthms](https://discourse.pijul.org/u/lthms)\
**Post date:** [June 2, 2017, 4:11pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26/5 "2017-06-02T16:11:45Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![spacefrogg](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/spacefrogg/32/37_2.png) [@spacefrogg](https://discourse.pijul.org/u/spacefrogg)\
**Post date:** [September 7, 2017, 7:28pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26/6 "2017-09-07T19:28:50Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![lthms](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/lthms/32/124_2.png) [@lthms](https://discourse.pijul.org/u/lthms)\
**Post date:** [September 7, 2017, 10:12pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26/7 "2017-09-07T22:12:55Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![spacefrogg](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/spacefrogg/32/37_2.png) [@spacefrogg](https://discourse.pijul.org/u/spacefrogg)\
**Post date:** [September 8, 2017, 6:15am UTC](https://discourse.pijul.org/t/pijul-man-pages/26/8 "2017-09-08T06:15:49Z")

</div>

I just stumbled upon [rust-rst](https://github.com/flying-sheep/rust-rst), which uses reStructuredText instead of asciidoc. Might be worth a look, too.

---

<div class="post-metadata">

**Author:** ![pmeunier](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/pmeunier/32/4_2.png) [@pmeunier](https://discourse.pijul.org/u/pmeunier)\
**Post date:** [September 8, 2017, 7:11am UTC](https://discourse.pijul.org/t/pijul-man-pages/26/9 "2017-09-08T07:11:00Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![spacefrogg](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.pijul.org/spacefrogg/32/37_2.png) [@spacefrogg](https://discourse.pijul.org/u/spacefrogg)\
**Post date:** [September 8, 2017, 12:30pm UTC](https://discourse.pijul.org/t/pijul-man-pages/26/10 "2017-09-08T12:30:17Z")

</div>

> [@pmeunier](#):
>
> It doesn’t generate man pages, but I would bet this is already implemented, or at least reasonably easy to do.

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.