[semi-OT] Writiing manpages (the practical way)

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

[semi-OT] Writiing manpages (the practical way)

Jeanette C.
Hey hey,
I'd like to write a manpage for a small program that I have and I'd also like
to practise. So I've been wondering what the real developers use.

Are you writing your manpages straight in (G)ROFF or is there a "modern"
pre-preprocessor that is widely used?

My research didn't yield anything conclusive. I have seen mention of a few
systems that can be translated into ROFF, but I couldn't really spot an
obvious candidate.

I am writing c++ and use cmake, in case that might influence an answer either
way.

Best wishes,

Jeanette

--
  * Website: http://juliencoder.de - for summer is a state of sound
  * Youtube: https://www.youtube.com/channel/UCMS4rfGrTwz8W7jhC1Jnv7g
  * SoundCloud: https://soundcloud.com/jeanette_c
  * Twitter: https://twitter.com/jeanette_c_s
  * Audiobombs: https://www.audiobombs.com/users/jeanette_c
  * GitHub: https://github.com/jeanette-c

Top down, on the strip
Lookin' in the mirror
I'm checkin' out my lipstick <3
(Britney Spears)
_______________________________________________
Linux-audio-user mailing list
[hidden email]
https://lists.linuxaudio.org/listinfo/linux-audio-user
Reply | Threaded
Open this post in threaded view
|

Re: [semi-OT] Writiing manpages (the practical way)

wferi
"Jeanette C." <[hidden email]> writes:

> I'd like to write a manpage for a small program that I have and I'd
> also like to practise. So I've been wondering what the real developers
> use.
>
> Are you writing your manpages straight in (G)ROFF or is there a
> "modern" pre-preprocessor that is widely used?

Straight groff isn't too bad, though I'm an old-school LaTeX fan.
Anyway, man(7) provides usable documentation.  I'd expect CMake to
support it, but I've got Automake experience only.

I also use pod2man, mostly for scripts which can easily embed their
documentation.  This helps with not forgetting to update the manpage,
but isn't standard and somewhat limiting with fancy stuff.

For API documentation (not for now) there is doxygen2man.
--
Feri
_______________________________________________
Linux-audio-user mailing list
[hidden email]
https://lists.linuxaudio.org/listinfo/linux-audio-user
Reply | Threaded
Open this post in threaded view
|

Re: [semi-OT] Writiing manpages (the practical way)

Joel Roth-2
In reply to this post by Jeanette C.
Hey hey,

If you don't mind working directly with roff commands,
you can just use an existing man page source as as
starting point.

If you like markdown, here is a project that converts
markdown to man page. Punning on 'roff', it is called 'ronn'.

http://rtomayko.github.io/ronn/

When I write man pages I use pod, a simple markup originally
created for writing man pages for perl programs.  Pod can be
converted to roff, html, texinfo, latex, ascii and other
formats.  In contrast with markdown, the text style is
giving by a letter followed by text in angle brackers, for
example, B<bold text>.

Happy authoring!

--
Joel Roth
_______________________________________________
Linux-audio-user mailing list
[hidden email]
https://lists.linuxaudio.org/listinfo/linux-audio-user
Reply | Threaded
Open this post in threaded view
|

Re: [semi-OT] Writiing manpages (the practical way)

Jacob-10
In reply to this post by Jeanette C.
On 22.04.20 11:12, Jeanette C. wrote:
> Hey hey,
> I'd like to write a manpage for a small program that I have and I'd also
> like to practise. So I've been wondering what the real developers use.

I have been using the help2man program in such cases which creates a man
page by running your executable using the --help and --version options
(which should follow the GNU guidelines) and parsing the output. You can
either tweak the output by using command line options or at least use it
as starting point for further modifications.

HTH
Jacob
_______________________________________________
Linux-audio-user mailing list
[hidden email]
https://lists.linuxaudio.org/listinfo/linux-audio-user
Reply | Threaded
Open this post in threaded view
|

Re: [semi-OT] Writiing manpages (the practical way)

Jeanette C.
In reply to this post by wferi
Hi there,
thanks all of you for the valuable tips.

@Jacob: help2man I didn't see, but sounds easy for a small tool.

I had spotted pod2man, but wasn't sure how much it is still bound to Perl
projects.

Basically they all sound very reasonable, including straight ROFF.

My point was to see what - and if - there is a modern standard using something
else, since I can start afresh and would like to create something which is
well maintainable, possibly easy to export and fits well into the bigger
context and widely used.

It appears that the landscape here is diverse.

Thanks for chiming in and giving me informed feedback.

Best wiishes,

Jeanette

--
  * Website: http://juliencoder.de - for summer is a state of sound
  * Youtube: https://www.youtube.com/channel/UCMS4rfGrTwz8W7jhC1Jnv7g
  * SoundCloud: https://soundcloud.com/jeanette_c
  * Twitter: https://twitter.com/jeanette_c_s
  * Audiobombs: https://www.audiobombs.com/users/jeanette_c
  * GitHub: https://github.com/jeanette-c

Skip on the drinks Head to the floor
Makin' my way Past the show
My body's taken over And I want some more <3
(Britney Spears)
_______________________________________________
Linux-audio-user mailing list
[hidden email]
https://lists.linuxaudio.org/listinfo/linux-audio-user
Reply | Threaded
Open this post in threaded view
|

Re: [semi-OT] Writiing manpages (the practical way)

Dennis Schulmeister-Zimolong
In reply to this post by Jacob-10
Hi all,

I can also recommend help2man, provided the program follows the general
--help and --version convention. I had very good experience with it for
some of my python programs. help2man takes the output of the program
to generate the man page and merges it with a custom groff/text file
for additional sections.

Kind regards,
Dennis

On Wed, 22 Apr 2020 12:52:42 +0200
Jacob <[hidden email]> wrote:

> On 22.04.20 11:12, Jeanette C. wrote:
> > Hey hey,
> > I'd like to write a manpage for a small program that I have and I'd
> > also like to practise. So I've been wondering what the real
> > developers use.
>
> I have been using the help2man program in such cases which creates a
> man page by running your executable using the --help and --version
> options (which should follow the GNU guidelines) and parsing the
> output. You can either tweak the output by using command line options
> or at least use it as starting point for further modifications.
>
> HTH
> Jacob
> _______________________________________________
> Linux-audio-user mailing list
> [hidden email]
> https://lists.linuxaudio.org/listinfo/linux-audio-user
_______________________________________________
Linux-audio-user mailing list
[hidden email]
https://lists.linuxaudio.org/listinfo/linux-audio-user