man pages

[AladW]

(left out the template because it counts as a feature request I guess)

Opening this issue to keep track of man page progress and collect ideas. I had the following layout in mind:

• README.md (compare yay/README.md, aurutils/README.md)
  • Short description of the project
  • Screenshots
  • Available man pages
  • FAQ, Features
• aurman(1)
  • SYNOPSIS
  • DESCRIPTION
  • OPTIONS
    • Native pacman options
    • aurman options
• aurman_config(5) (compare makepkg.conf(5))
  • SYNOPSIS
  • DESCRIPTION
  • OPTIONS

Optional stuff:

• aurmansolver(7) - Not sure this is a good idea since there's long code fragments and man pages have no syntax highlighting.

Implementation:

• Manual
  • Pros:
    • apart from escaping some characters, groff_man is quite pleasant to write imo since you have a few short macros for most things.
    • changes can be viewed directly with man -l foo.1
  • Cons:
    • No live preview on github. (syntax highlighting for groff is still available)
• Some conversion tool, e.g. pandoc
  • Pros:
    • When written in markdown or reStructuredText, can be viewed live in github or some other platform like readthedocs.io
  • Cons:
    • Additional step to create the man page for the local system
    • Generated output resembles a war zone

If you decide for the manual approach I can format the initial man pages. If not it should be mostly a matter of copy/paste from the README.

[AladW]

Note that you can also write man pages in groff and convert it back to markdown for readthedocs. Whenever I tried this, the result looked like modern art instead of readable documentation... perhaps this has improved since then. If it has, it would combine the benefits of both approaches described above.

[polygamma]

It's been over a month, I am actually not planning to work on this by myself, but it's still a valid improvement, hence I won't close this issue. Nevertheless: If one wants to have actual man pages, that one has to do it, because I am not interested in doing it, I like my README.

[Morganamilo]

Maybe include the readme in the built package. Then it can at least be accessed locally. /usr/share/doc/aurman/README.md?

[AladW]

I haven't done any work on it, simply because I don't know on what implementation you prefer.

[AladW]

Apparently new versions of mdoc have an inbuilt markdown converter:

https://undeadly.org/cgi?action=article&sid=20170304230520

The reason for providing this output mode is not that i consider markdown a good, or even a half-decent, markup language. Quite to the contrary, I hereby offcially declare it the shittiest markup language i have seen so far. Basically, it hasn't any strong point whatsoever, but the downsides are numerous, scary, and cover practically every relevant aspect:

:smile:

If it works this would be the ideal solution.