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

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

[James]

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?


Comment and suggestions are most welcome.


(old dog in rehab)
James

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@gmail.com

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

[Martin Vaeth]

James <wireless@tampabay.rr.com> wrote:
>
> So instead of my spew of ascii information files, I'm now composing
> 'man pages' mostly using txt2man.

If you want to avoid learning *roff, there is also e.g. pod from perl
which gives you simple basic markup functionality and can output in
man page format (and other format).
For other formats, there are also tools like docutils or texinfo.
If you want something which should eventually be printed (on paper),
I would strongly recommend to learn LaTeX to get professional results.

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

[Joerg Schilling]

Martin Vaeth <martin@mvath.de> wrote:

> James <wireless@tampabay.rr.com> wrote:
> >
> > So instead of my spew of ascii information files, I'm now composing
> > 'man pages' mostly using txt2man.
>
> If you want to avoid learning *roff, there is also e.g. pod from perl
> which gives you simple basic markup functionality and can output in
> man page format (and other format).

For a simple instuction, see 

	man -s5 man

On BSD based classification, this may be section 7...

There are only a few macros to learn, so writing man pages is really simple.

BTW: Use other (good) man pages as reference and avoid the BSD doc format that 
was introduced while the AT&T lawsuit was active.

Jörg

-- 
 EMail:joerg@schily.net                    (home) Jörg Schilling D-13353 Berlin
       joerg.schilling@fokus.fraunhofer.de (work) Blog: http://schily.blogspot.com/
 URL:  http://cdrecord.org/private/ http://sourceforge.net/projects/schilytools/files/'

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

[James]

Joerg Schilling <Joerg.Schilling <at> fokus.fraunhofer.de> writes:


> 	man -s5 man

man 7 man

> BTW: Use other (good) man pages as reference and avoid the BSD doc format
> that  was introduced while the AT&T lawsuit was active.

Yea, I learned 'monkey see monkey' do a log time ago, to get along;
got an explicit example or template or guide in mind?

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

[Joerg Schilling]

James <wireless@tampabay.rr.com> wrote:

> Joerg Schilling <Joerg.Schilling <at> fokus.fraunhofer.de> writes:
>
>
> > 	man -s5 man
>
> man 7 man

If you like to read the original aman -s5 man, look here:

	http://schillix.sourceforge.net/man/man5/man.5.html

It contains a cookbook for a typical man page.

> > BTW: Use other (good) man pages as reference and avoid the BSD doc format
> > that  was introduced while the AT&T lawsuit was active.
>
> Yea, I learned 'monkey see monkey' do a log time ago, to get along;
> got an explicit example or template or guide in mind?

See man(5) above.

Also check the man pages from the schily tools that have been written to be 
highly portable. Eric Raymond contacted me several times when writing his
documentation tools...

If you like to get a name of a man page that contains most possible constructs, 
I recommend to read the revised Bourne Shell man page that was created for the 
portable Bourne Shell:

	http://schillix.sourceforge.net/man/man1/bosh.1.html

In contrast to the typical Solaris man pages that have been bowdlerized by a 

	troff -> sgml -> troff 

conversion using bad tools, my Bourne Shell man page has been manully fixed to 
again follow the man style rules. This corrected Bourne Shell man source also 
verifies that a troff based man page is really readable in source as well. Note 
that a typical man page should be written as floating text and prefer the *roff
macros from man(5) in favor of \f font switches if possible.

See:

	https://sourceforge.net/projects/schilytools/files/

for a schily tools tarball.

Jörg

-- 
 EMail:joerg@schily.net                    (home) Jörg Schilling D-13353 Berlin
       joerg.schilling@fokus.fraunhofer.de (work) Blog: http://schily.blogspot.com/
 URL:  http://cdrecord.org/private/ http://sourceforge.net/projects/schilytools/files/'

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

[Grant Edwards]

On 2015-06-03, Martin Vaeth <martin@mvath.de> wrote:
> James <wireless@tampabay.rr.com> wrote:
>>
>> So instead of my spew of ascii information files, I'm now composing
>> 'man pages' mostly using txt2man.
>
> If you want to avoid learning *roff, there is also e.g. pod from perl
> which gives you simple basic markup functionality and can output in
> man page format (and other format).

asciidoc, markdown, and reStructuredText can all generate man page
format as well as HTML, PDF, and others.  The main benefit of these is
that they're also easy to read in their "raw" input format (unlike
roff).

-- 
Grant Edwards               grant.b.edwards        Yow! I want to dress you
                                  at               up as TALLULAH BANKHEAD and
                              gmail.com            cover you with VASELINE and
                                                   WHEAT THINS ...

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

[Peter Humphrey]

On Wednesday 03 June 2015 14:24:18 Grant Edwards wrote:
> On 2015-06-03, Martin Vaeth <martin@mvath.de> wrote:
> > James <wireless@tampabay.rr.com> wrote:
> >> So instead of my spew of ascii information files, I'm now composing
> >> 'man pages' mostly using txt2man.
> > 
> > If you want to avoid learning *roff, there is also e.g. pod from perl
> > which gives you simple basic markup functionality and can output in
> > man page format (and other format).
> 
> asciidoc, markdown, and reStructuredText can all generate man page
> format as well as HTML, PDF, and others.  The main benefit of these is
> that they're also easy to read in their "raw" input format (unlike
> roff).

Isn't there a Gentoo Way too? I can't put my finger on it just now but I think 
I've seen a reference to producing Gentoo docs, including man pages.

-- 
Rgds
Peter

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

[Grant Edwards]

On 2015-06-03, Peter Humphrey <peter@prh.myzen.co.uk> wrote:
> On Wednesday 03 June 2015 14:24:18 Grant Edwards wrote:
>> On 2015-06-03, Martin Vaeth <martin@mvath.de> wrote:
>> > James <wireless@tampabay.rr.com> wrote:
>> >> So instead of my spew of ascii information files, I'm now composing
>> >> 'man pages' mostly using txt2man.
>> > 
>> > If you want to avoid learning *roff, there is also e.g. pod from perl
>> > which gives you simple basic markup functionality and can output in
>> > man page format (and other format).
>> 
>> asciidoc, markdown, and reStructuredText can all generate man page
>> format as well as HTML, PDF, and others.  The main benefit of these is
>> that they're also easy to read in their "raw" input format (unlike
>> roff).
>
> Isn't there a Gentoo Way too? I can't put my finger on it just now
> but I think I've seen a reference to producing Gentoo docs, including
> man pages.

The only thing I know of is GuideXML which is used to generate the
user guide:

  https://wwwold.gentoo.org/doc/en/xml-guide.xml

I'm not aware of it generating anything other than docbook or HTML,
but maybe you could use something like this to then convert from
docbook to man:

https://www.oasis-open.org/docbook/tools/dtm/
  
-- 
Grant Edwards               grant.b.edwards        Yow! I hope something GOOD
                                  at               came in the mail today so
                              gmail.com            I have a REASON to live!!

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

[Jc García]

2015-06-03 9:14 GMT-06:00 Peter Humphrey <peter@prh.myzen.co.uk>:

> Isn't there a Gentoo Way too? I can't put my finger on it just now but I think
> I've seen a reference to producing Gentoo docs, including man pages.
>
Portage uses roff[1], so I don't think there is a gentoo specific way.
[1] https://github.com/gentoo/portage/blob/master/man/emerge.1

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

[James]

Grant Edwards <grant.b.edwards <at> gmail.com> writes:


> asciidoc, markdown, and reStructuredText can all generate man page
> format as well as HTML, PDF, and others.  The main benefit of these is
> that they're also easy to read in their "raw" input format (unlike
> roff).

I could not find 'restructuretext'; got a resource location?

I guess I'm going to have to brush on  *roff codes. 'troff' is
what I used, but it has been a very long time......

thx,
James

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

[Marc Joliet]

[-- Attachment #1: Type: text/plain, Size: 722 bytes --]

Am Wed, 3 Jun 2015 15:34:13 +0000 (UTC)
schrieb James <wireless@tampabay.rr.com>:

> Grant Edwards <grant.b.edwards <at> gmail.com> writes:
> 
> 
> > asciidoc, markdown, and reStructuredText can all generate man page
> > format as well as HTML, PDF, and others.  The main benefit of these is
> > that they're also easy to read in their "raw" input format (unlike
> > roff).
> 
> I could not find 'restructuretext'; got a resource location?

http://docutils.sourceforge.net/rst.html

reStructuredText is often used in Python docstrings, which is where I
encounter it the most.

-- 
Marc Joliet
--
"People who think they know everything really annoy those of us who know we
don't" - Bjarne Stroustrup

[-- Attachment #2: Digitale Signatur von OpenPGP --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

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

[Grant Edwards]

On 2015-06-03, James <wireless@tampabay.rr.com> wrote:
> Grant Edwards <grant.b.edwards <at> gmail.com> writes:
>
>
>> asciidoc, markdown, and reStructuredText can all generate man page
>> format as well as HTML, PDF, and others.  The main benefit of these is
>> that they're also easy to read in their "raw" input format (unlike
>> roff).
>
> I could not find 'restructuretext'; got a resource location?

https://www.google.com/search?q=reStructuredText

> I guess I'm going to have to brush on *roff codes. 'troff' is what I
> used, but it has been a very long time......

The easiest thing to do is to grab the source for an existing man page
and start editing...

-- 
Grant Edwards               grant.b.edwards        Yow! GOOD-NIGHT, everybody
                                  at               ... Now I have to go
                              gmail.com            administer FIRST-AID to my
                                                   pet LEISURE SUIT!!

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

[Joerg Schilling]

Grant Edwards <grant.b.edwards@gmail.com> wrote:

> The easiest thing to do is to grab the source for an existing man page
> and start editing...

If you use one of sufficient quality ;-)

Jörg

-- 
 EMail:joerg@schily.net                    (home) Jörg Schilling D-13353 Berlin
       joerg.schilling@fokus.fraunhofer.de (work) Blog: http://schily.blogspot.com/
 URL:  http://cdrecord.org/private/ http://sourceforge.net/projects/schilytools/files/'

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

[James]

Martin Vaeth <martin <at> mvath.de> writes:


> > So instead of my spew of ascii information files, I'm now composing
> > 'man pages' mostly using txt2man.
> 
> If you want to avoid learning *roff, there is also e.g. pod from perl
> which gives you simple basic markup functionality and can output in
> man page format (and other format).

Pod leaves me with too many choices. Can you narrow it down?

eix -3 pod returns nothing. An overlay perhaps?


> For other formats, there are also tools like docutils or texinfo.
> If you want something which should eventually be printed (on paper),
> I would strongly recommend to learn LaTeX to get professional results.

Wow. I have not use latex since decades ago. If I want to print a man
page, I just cat it a file and upload it into libreoffice for printing.

I still have a very old latex manual (version 2.09 by Leslie Lamport
of Digital Equipment corp). I wrote my masters thesis in Latex, much
to the University's chagrin......

eix latex returns too many choices. What is the best one(s) to install
to play iwth latex again? Why is this better can just using libreoffice
once the files are in man page format?

James

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

[Martin Vaeth]

James <wireless@tampabay.rr.com> wrote:
>
> Pod leaves me with too many choices. Can you narrow it down?

pod (and pod2*) is part of perl. Very likely it is already installed.
man perlpod (or "perldoc pod::perlpod" if the former does not work
on your system).

> eix latex returns too many choices. What is the best one(s) to install
> to play iwth latex again?

Nowadays there is practically only texlive - everything else
are just various tools for it: emerge texlive
(which has enormous dependencies - be sure to
set in the USE-Flags what you really need)

> Why is this better can just using libreoffice
> once the files are in man page format?

I meant to write it in latex *instead* of man page format
if your main aim is a really professional print. All
general-purpose conversions from one format to another
loose something, in general. If your manpage is simple
enough, it probably does not matter, but the more complex
things you need (enumerations within enumerations, perhaps
with intermediate texts, footmarks - perhaps footmarks
within footmarks - perhaps even semi-graphical elements like
braces under texts, etc. pp) the less likely is that you
find a format which serves all your needs.
Funny: I just realize that there is a pod2latex converter
in the tree. However, keep in mind that pod is *very* poor
compared to latex...