[SOLVED] Manpage, is it really that simple?

[sea]

Heyas

After reading a few page about creating man pages, i tried to callup the plain text file with man.
It worked, actual looked even better then after modifications with nroff or groff.

Pages i've read:
http://www.linuxhowtos.org/System/creatingman.htm
http://www.fnal.gov/docs/products/up.../manpages.html
http://anaturb.net/create_man_p.htm

A first try looks like: /tmp/tstman

.TH rmtf 1 "2012 March 21" "Version 0.5.0" "sea Script Collection"
.SH NAME
rmtf

.SH SYNOPSIS
rmtf [PATH]

.SH DESCRIPTION
ReMove Temp Files recursivly, either from current directory, or in the PATH provided.

.SH AUTHOR
Name:   Simon A. Erat
.br
Email:  erat.simon@gmail.com

And shows up properly when called with:

man /tmp/tstman

I understand the step after, gzip'ing but i 'sort' that part to be old school,where one needed those extra bits saved on the 720kb floppy


This confused me, as i wonder why would one actualy need to pipe or parse them through nroff or groff?
Is this step really required?

[RupertPupkin]

Piping to groff is only necessary if you want some other format for the manpage, typically PostScript which can be converted to PDF. For example, this will give you a PDF version of the grep manpage:

man -t grep | ps2pdf - grep.pdf

Some developers make PDF versions of their manpages because they're lazy and don't want to write a full user manual , plus it's an easy way of writing documentation that can be downloaded and viewed by anyone without needing to be on a Linux/UNIX machine, and it looks good when printed.

[sea]

Word.

Right at this moment, i have to write like, dont know... 30 to 50 pages... and as i understand you, its NOT required to be properly displayed with MAN.
But it might be, if/when i want to provide something like a pdf.

[Alberth5674764]

Except Word is pretty much useless as cross-platform documentation format.
I tend to use LaTeX, but you may want to use some open office program instead.

[Gareth Jones]

Alberth5674764, I believe sea was saying work as in http://www.urbandictionary.com/define.php?term=word.

As much as he should say "latex" instead, I think people would look at him funny...

[Alberth5674764]

rofl

You learn something new every day!
Thanks for explaining

[jpollard]

Man pages really are simple.

Formatting/tagging is done with "." in the first column, what follows is the directive.

Early in the nroff/troff history, there were other options for processing text - tbl (translated tables into troff commands), pic (translated plots/diagrams into troff), eqn (equations), refer (cross references) and toc (table of contents). Others existed for esoteric formating (chemical formula and more). The output of each of these "preprocessors" would be the input, with the macros for that particular processor translated into macros/troff directives for following interpretation.

The macros provided (the .name stuff) is translated into troff (typesetting runoff). nroff is the same as troff, but it generates simple ascii control codes as defined by the TERM environment variable.

There is/was an indexer available for handling large documents.

The "man" command was a simple script that piped the various formatters in order, and passed them to the troff/nroff formatter for handling the "man" macros.

Remember, when this started process memory was limited to 64K bytes... so complex operations would be broken down giving each process a relatively simple thing to do. The way tbl worked was to translate tbl macros into the underlying format. Anything tbl didn't recognize was passed without change - assuming something later would translate it. I seem to remember the order was eqn, pic, tbl, refer, toc, troff. This allows equations to be embeded in diagrams, diagrams embeded in tables, and tables in the final macro processing. The printed output still had to be put in the right order if all were processed in one step (the table of contents would be last so that it could show the cross reference index page).

Breaking the problem up allowed for very elaborate documents to be created, and optimization by dropping passes that didn't apply.

[RupertPupkin]

Originally Posted by jpollard

Early in the nroff/troff history, there were other options for processing text - tbl (translated tables into troff commands), pic (translated plots/diagrams into troff), eqn (equations), refer (cross references) and toc (table of contents).

And don't forget grap, which lets you create graphs of functions. There's a free version here. The mm and ms macros also made typesetting easier.

You can do some cool typesetting with groff, which comes by default with every Linux system and is pretty small (unlike more complicated systems, like LaTeX, which is a huge program). For example, if you save this code in a text file called mathquiz.roff:

.PH ""
.EQ
delim $$
.EN
.ce 1
\s+3\fBMath Quiz\fP  \(rh \fIShow all work!\fP \(lh\s0
.LB 3 0 0 1
.LI
Calculate the following:
.LB 3 0 0 2 a)
.LI
$int sub 0 sup a sqrt{( x + pi ) sup 3} ~ dx$ for $a ~>=~ 0$
.sp 10
.LI
$sum from {n = 1} to {inf} {3 over {10 sup n}}$
.LE
.sp 8
.LI
Find the area of the intersection of the four circles below:
.PS
for i = 0 to 1 do {
   for j = 0 to 1 do {circle radius 1 at i,j}
}
line from 0,0 to 1,0 "5" below
line from 1,0 to 1,1 " 5" ljust
line from 1,1 to 0,1 "5" above
line from 0,1 to 0,0 "5 " rjust
.PE
.LE

then run this command:

groff -p -e -mm mathquiz.roff | ps2pdf - mathquiz.pdf

You should get a PDF file with math symbols and a drawing. That command uses the pic and eqn preprocessors with the mm macro. The default output is PostScript, so ps2pdf converts it to PDF.
If you prefer a Helvetica font:

groff -f H -p -e -mm mathquiz.roff | ps2pdf - mathquiz.pdf

There's a free book on troff co-written by Tim O'Reilly himself, which can still be used for groff, available here. And if you want a text editor with syntax highlighting for *roff files, you can use nroff-mode in Emacs (Alt-x nroff-mode).

Edit: Here's what the PDF output of the above code looks like: