Re: [gentoo-user] writing man pages (gentoo conventions)

[Alan McKinnon]

On 03/06/2015 06:21, James wrote:
> Ok,
>
> So instead of my spew of ascii information files, I'm now composing
> 'man pages' mostly using txt2man. What I was wondering is what
> sort of template do folks use to help get the quickly/sporadically written
> ascii notes into more of a 'preprocessed' form, then conversion to
> man pages. Most of the codes I've written are on microprocessors and
> it's ugly C/assembler code and nothing like manpages. I have for decades
> just 'marked up' (digital) specifications and given back to customers. Now
> that I'm coding for lots of others to see the codes, I feel embarrassed
> (not really, but you know gotta act like I am embarrassed.) Actually,
> I don't give a crap because I always got stuck with the math functions
> an converting legalese into C_logic .....
>
> But now, I'm turning over a new leaf.....(really).
>
>
> I jot down notes in ascii files while I code and figure things out.
> Surely there is a better way for an old vi_hack to get more cleanly
> organized so these notes are at least in an ugly man page and more
> presentable to the masses (of critical eyes)?
>
> Note: I do not want an overburdened semantic here, just a wee bit
> cleaner and easier ascii_methodology to prepare for others to read ascii
> notes and such.....
>
> Formal Man pages are found in /usr/share/man, but for my work would it
> be best to put the one I create into /usr/local/man or /usr/local/share/man
> or ???? What do others do?

You probably want to run "man man" and read it :-)

Stick to the established conventions that folks are used to, like
section heading , and put your pages in the most relevant category (1-9)

Location: The convention is that code tarballs ship with
PREFIX=/usr/local, and packagers set it to the sae named location
directly under /usr. So your stuff goes in /usr/local/share/man



-- 
Alan McKinnon
alan.mckinnon@×××××.com