Convert documentation to man pages

yestax commented

2026-04-09 17:25:38 +02:00

Owner

Man pages are preffered over plain text.

They can be seen with man command (Using vim for instance).
They can be searched with apropos command.

It's difficult to make one by hand but it may be easy with pandoc.
Also they may be stored as markdown and generated during package build via dh_auto_build in rules.

Man pages are preffered over plain text. They can be seen with man command (Using vim for instance). They can be searched with apropos command. It's difficult to make one by hand but it may be easy with pandoc. Also they may be stored as markdown and generated during package build via dh_auto_build in rules.

yestax added the

enhancement

label

2026-04-09 17:25:38 +02:00

yestax referenced this issue

2026-04-13 10:01:47 +02:00

Documentation install location #38

yestax added this to the Setup v1.3.X milestone

2026-04-30 18:51:51 +02:00

yestax commented

2026-05-05 22:15:32 +02:00

Author

Owner

https://eddieantonio.ca/blog/2015/12/18/authoring-manpages-in-markdown-with-pandoc/

yestax commented

2026-05-05 23:32:23 +02:00

Author

Owner

$ pandoc -D man to get a template for man pages

yestax commented

2026-05-05 23:41:29 +02:00

Author

Owner

to generate the file
$ pandoc --standalone --to man filestructure.7.md -o filestructure.7

to read it locally
$ man -l filestructure.7

to generate the file $ pandoc --standalone --to man filestructure.7.md -o filestructure.7 to read it locally $ man -l filestructure.7

yestax commented

2026-05-06 19:08:01 +02:00

Author

Owner

base
bash
debian
git
packaging
python
ruby
vim

- [X] base - [x] bash - [x] debian - [x] git - [x] packaging - [x] python - [x] ruby - [x] vim

yestax commented

2026-05-07 12:22:36 +02:00

Author

Owner

It is possible to use a custom manual section, to not interact with any other one. It is possible to even use a string.

if stored in /usr/share/man/man

it can be queried with man

If no other names collide it can even be queried with man and will go through all the sections.

This should be useful because a lot of documentation are additional informations on existing utilities. Section 7 is great but can collide (example schroot uses section 7).

mansetup or mankb can be used for instance

It is possible to use a custom manual section, to not interact with any other one. It is possible to even use a string. if stored in /usr/share/man/man<section> it can be queried with man <section> <filename> If no other names collide it can even be queried with man <filename> and will go through all the sections. This should be useful because a lot of documentation are additional informations on existing utilities. Section 7 is great but can collide (example schroot uses section 7). mansetup or mankb can be used for instance

yestax commented

2026-05-16 11:26:43 +02:00

Author

Owner

A 'setup' man section is hard to do since man doesn't recognise setup as a section.
To properly work it needs an entry in /etc/manpath.config otherwise it just thinks it's a man page and search for it.

To avoid collision, an idea is to use a man subsection. For instance .8setup files in man8 dir. Then man search in the section order and can find another page before but it's okay since the page can still be queried with the 8setup fullname.

A 'setup' man section is hard to do since man doesn't recognise setup as a section. To properly work it needs an entry in /etc/manpath.config otherwise it just thinks it's a man page and search for it. To avoid collision, an idea is to use a man subsection. For instance .8setup files in man8 dir. Then man search in the section order and can find another page before but it's okay since the page can still be queried with the 8setup fullname.

yestax commented

2026-05-28 00:49:04 +02:00

Author

Owner

solved by #82

yestax closed this issue

2026-05-28 00:49:04 +02:00

yestax referenced this issue

2026-05-28 14:17:30 +02:00

Documentation install location #38

Rows
Columns

Convert documentation to man pages #32