Writing and Publishing with Linux

Table of Contents

last revision
27 October 2011, 6:33pm
book quality
not very good

,

Markdown ‹↑›

The markdown system uses a minimalist structured text format to produce html. 'markdown' is both a 'text format' and also a perl script used to turn that format into html. Using pandoc it is possible to convert markdown formatted text into other formats, such as pdf. Markdown may fill a gap between enscript and latex, where the user wants more control over how the produced document looks than can be obtained with 'enscript', but doesnt wish to become mired down in the complexities of 'latex'

www: http://daringfireball.net/projects/markdown/
details about the format of the source document (text file).
www: http://daringfireball.net/projects/markdown/dingus
a page to actually try out markdown text syntax
www: http://six.pairlist.net/pipermail/markdown-discuss/
the markdown discussion list archives

Converting To Html ‹↑›

The 'markdown' perl script can only create html but 'pandoc' can produce other formats from the same markdown source text document. Markdown only seems to produce a 'fragment' of html (without head and body tags)

display a text document converted to html with markdown

 markdown document.txt | less

convert a document to html and save as 'doc.html'

 markdown doc.txt > doc.html

convert a document and add html and body tags to make a complete page

 (echo '<html><body>';markdown doc.txt;echo '</body></html>') > out.html
 markdown doc.txt|sed '1s/^/<html><body>/;$s.$.</body></html>.' > out.html
 pandoc -s -o out.html doc.txt  the same but better, using pandoc

Markdown Syntax ‹↑›

The great advantage of markdown syntax is that the source document can be kept 'clean' without distracting or ugly markup codes. Normal html can be inserted anywhere in a markdown document. If there is anything which markdown cannot do (such as tables) just use html tags instead.

Document Headings ‹↑›

create a 1st-level document heading (underline the text with '=' equals)

   The Heading
   ===========

create a markdown 2nd-level document heading

   A Second Level Heading

markup a 3rd level document heading 'Stone Fruit'

 ### Stone Fruit

create a vim command ',ll' which underlines the current line with '-' dashes

 map ,ll yyp:s/[ ]*$// \| s/[ ]*$// \| s/[^ ]/-/g \| s/- /--/g<cr>o
place in 'vimrc'. This mapping helps to write markdown 2nd level headings

create a vim command ',LL' which creates a markdown 1st level heading

 map ,ll yyp:s/[ ]*$// \| s/[ ]*$// \| s/[^ ]/=/g \| s/= /==/g<cr>o
This mapping command underlines the current line with '=' equals

create a 'blockquote', that is text more indented than surrounding paragraphs

 >   ##(blockquotes can contain headings and paragraphs

Text Emphasis ‹↑›

make a word or phrase emphasised

 the following is *emphasised text*
 the following is _emphasised text_   more or less the same

strongly emphasise words or phrases

 the following is **strongly emphasised text**
 the following is __strongly emphasised text__

Lists ‹↑›

The list marker can also be a '+' or a '*'. There is no difference between these types of lists

create an unordered (bulleted) list

   - first item
   - second item
   - third and last

create an nested unordered list

   - first item
     * sublist item 1
     * sublist item 2
   - second item
   - third and last

create an ordered list with a nested unordered list

    1.  First
    2.  Second:
        -   Fee
        -   Fie
        -   Foe
    3.  Third

create an unordered list with links to other parts of the page

   - [Chapter One](#chap1) 
   - [Chapter Two](#chap2) 
   - [Chapter Three](#chap3) 
   <h2 id='chap1'>...</h2>
   <h2 id='chap2'>...</h2>
notice how normal html is used to create the anchors

create an ordered list

   1. first
   2. second
   3. third

Links ‹↑›

create link in a document with the display text 'example link'

 This is an [example link](http://example.com/)
the html: this is an <a href="http://example.com/">example link</a>.</p>

create link with a display text and also a 'title' (when the mouse hovers over)

 [example link](http://example.com/ "With a Title")

for pdf output the embedded code backtick may look best

 `http://google.com`   displays the link in fixed pitch font in pdf

create and use a named link with display text 'Google'

   a search engine is [Google][1]
   [1]: http://www.google.com     "Google"
   [2]: http://www.yahoo.com      "Yahoo"

  * create a reference link with a space in the name
   I start my morning with a cup of coffee and
   [The New York Times][NY Times].

   [ny times]: http://www.nytimes.com/

Images ‹↑›

embedd an image file in the document, with an optional title ![a tree](/path/to/img.jpg "Title") if the image is not found show 'tree'

embedd an image in the document using the 'reference' style syntax

  ![alt text][id]

  [id]: /path/to/img.jpg "Title"

Embedded Code ‹↑›

use backticks '`' to show code with special characters in it

 dont use the `<blink>` tag

another example

 html entities can be named `&mdash;` or numbered `&#8212;`.

use 4 spaces or 1 tab of indentation to display a paragraph of code

use a backslash to escape special characters

 \*   this prints an asterix

create a horizontal rule using 3 or more dashes, asterixes etc

 ---
 * * *  the same

Gotchas ‹↑›

The table dashes must begin in the 5th column all later for the table to be formatted correctly.

Pandoc Markdown Syntax ‹↑›

Pandoc allows a number of extensions to markdown syntax to allow for structures such as tables. These extensions can be turned off with the '--strict' switch

www: johnmacfarlane.net/pandoc/README
an example of a pandoc markdown document
www: johnmacfarlane.net/pandoc/README.html#pandocs-markdown-vs.standard-markdown
details about the pandoc extensions to the markdown syntax
create subscripts and superscripts
 H~2~O is a liquid.  2^10^ is 1024.

create text P with 'a cat' superscripted

 P~a\ cat~  note the escaped backslash in the superscript

format text which is 'struck out', that is, has a bar through it

 This ~~is deleted text.~~

create compact definition lists

  Term 1
    ~ Definition 1
  Term 2
    ~ Definition 2a
    ~ Definition 2b

single brace links (also allowed in modern markdown syntax)

  1. Here's my [link]
  2. Here's my [link][]
  [link]: linky.com

inline footnotes

    Here is an inline note.^[Inlines notes are easier to write, since
    you don't have to pick an identifier and move down to type the note.]

footnotes

    Here is a footnote reference,[^1] and another.[^longnote]

    [^1]: Here is the footnote.
    [^longnote]: lots of text

create a table with a caption (use the underline to dictate the alignment)


      Right     Left     Center     Default
    -------     ------ ----------   -------
         12     12        12            12
        123     123       123          123
          1     1          1             1

    Table:  Demonstration of simple table syntax.

The table dashes must start in the 5th (?) or greater column of the source text file. The table is rendered in a fixed pitch font with the dashes.

create a table with no headers

    -------     ------ ----------   -------
         12     12        12            12
        123     123       123          123
          1     1          1             1
    -------

A Table must end with a blank line. Multiline tables are also possible.

source code blocks (begin and end with >3 tilde '~' characters)

   ~~~
    code
   ~~~

source code blocks with syntax highlighting and numbered lines

   ~~~~~~~ {.haskell .numberLines}
   qsort []     = []
   qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
                  qsort (filter (>= x) xs) 
   ~~~~~~~

Syntax highlighting may only work in html output files

show what languages syntax highlighting pandoc supports

 pandoc --version

provide document meta-information (title, author, date)

     % Small Steps 
     % J Appleby, B Kernighan 
     % 21/4/2001 

html blocks within markdown documents

   <table>
       <tr>
         <td>*one*</td>
         <td>[a link](http://google.com)</td>
       </tr>
   </table>

links to the document sections automatically created

 See the section on [header identifiers](#header-identifiers-in-html).

The section heading 'Green Tree' becomes [link](#green-tree)

produce a 'presentation' slide show with pandoc and 's5' % Eating Habits % John Doe % March 22, 2005

# In the morning

- Eat eggs - Drink coffee

# In the evening

- Eat spaghetti - Drink wine

pandoc -w s5 -s eating.txt > eating.html ,,,

Pandoc ‹↑›

pandoc extends both the syntax of markdown (allowing tables for example) and also the number of formats to which markdown can be output, including most importantly 'pdf'. Pandoc can perform other nice tricks such as putting automatic tables of contents into documents based on the section headings.

Pandoc appears to be in active development (early 2010). Features such as 'tables' are only available in later versions of pandoc. And these versions are not available as debian packages.

www: http://johnmacfarlane.net/pandoc/README.html
the good user guide for pandoc
www: http://johnmacfarlane.net/pandoc/examples.html
example of converting markdown (et al) documents to other formats
www: http://groups.google.com/group/pandoc-discuss
the pandoc discussion news group

Installing Pandoc ‹↑›

install ghc6 which is a haskell compiler.

install the latest pandoc using the haskell 'cabal' tool

 cabal install pandoc

Basic Usage ‹↑›

convert a 'markdown' text document to html format with pandoc

 pandoc doc.txt
 pandoc -o out.html doc.txt              the same, html is the default
 pandoc doc.txt -o out.html              better?
 pandoc -f markdown doc.txt -o out.html  the same, but unnecessary

show what header is added to a latex output file

 pandoc -D latex

convert multiple markdown files and a references file to an html page

 pandoc -s ch1.txt ch2.txt refs.txt > book.html

Converting Documents ‹↑›

If an output or input format is not given then pandoc will guess based on the file-names supplied.

pandoc output formats
HTML - webpages
markdown -
LaTeX - the tex typesetting system
groff man - unix manual pages
RTF - can be opened in ms word for example
DocBook XML -
texinfo - ?
reStructuredText -
ConTeXt -
S5 HTML slide shows.

Some of the output formats are documented in the user guide but not in the man page.

convert a markdown document 'doc.txt' to xml docbook format saved in 'out.xml'

 pandoc -t docbook -o out.xml doc.txt
 pandoc --to docbook -o out.xml doc.txt       the same
 pandoc -w docbook -o out.xml doc.txt         the same again
 pandoc --write docbook -o out.xml doc.txt

DocBook XML:

 pandoc -s -S -w docbook README -o example9.db

convert 'pandoc.1.md' in markdown format to a unix man page 'eg10.1'

 pandoc -s -w man pandoc.1.md -o eg10.1

convert a 'markdown' text document to tex format with pandoc

 pandoc -o out.tex doc.txt

convert From LaTeX to markdown:

 pandoc -s example4.tex -o example5.text

convert a 'markdown' text file to a stand-alone latex file

 pandoc -s -o out.tex doc.txt

convert the file 'doc.txt' in markdown format to an html webpage 'doc.html'

 pandoc doc.txt

convert an input stream into the latex format saved as 'out.tex'

 cat doc.txt | pandoc -o out.tex

Creating Pdf Files ‹↑›

Pandoc uses 'pdflatex' to create pdf files from the source text document.

convert the file 'doc.txt' in markdown syntax to a printable pdf 'doc.pdf'

 markdown2pdf doc.txt

convert 'doc.txt' written in markdown format to the pdf file 'output.pdf'

 markdown2pdf -o output.pdf doc.txt

convert 'doc.txt' to a pdf file 'doc.pdf' which has a table of contents

 markdown2pdf --toc doc.txt

create a pdf file from 'doc.txt' with a table of contents and numbered sections

 markdown2pdf -N --toc doc.txt

create a pdf document called 'stdin.pdf' from the markdown document 'doc.txt'

 cat doc.txt | markdown2pdf

specify that the input format is html

 pandoc -f html doc.txt

convert the file 'input.txt' to pdf format on a non-utf8 system

 iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
 iconv -t utf-8 input.txt | markdown2pdf | iconv -f utf-8  better ??

PDF with numbered sections and a custom LaTeX header, compilable with 'xetex'

 markdown2pdf -N --template=mytemplate.tex --variable version=1.4 README --xetex --toc -o example
xetex may be good for international character sets

Converting To Texinfo ‹↑›

Texinfo is the format of the free software foundation, also known as gnu. Its not a pleasant format

convert markdown to a texinfo file

 pandoc README -s -o example19.texi

convert the texinfo source into 'info', html and pdf

    makeinfo example19.texi -o example19.info
    makeinfo example19.texi --html -o example19
    texi2pdf example19.texi  # produces example19.pdf

Converting To Html ‹↑›

convert the text file 'doc.txt' to html linking to css style sheet 'sty.css'

 pandoc -c sty.css doc.txt  doc.txt uses markdown syntax

display a markdown text document to an html page and send to standard output

 pandoc -s -o - doc.txt

HTML with smart quotes, table of contents, CSS, and custom footer:

 pandoc -s -S --toc -c pandoc.css -A footer.html README -o example3.html

Convert From Html ‹↑›

convert a webpage to the markdown format and save as 'eg.txt'

 html2markdown http://www.gnu.org/software/make/ -o eg.text

Halibut ‹↑›

www: http://www.chiark.greenend.org.uk/~sgtatham/halibut/
Halibut is a system for creating formatted documents in a variety of output formats such as html (web-pages) pdf (printable) ... Halibut, uses a terse plain text input format. Halibut does not fully support unicode. Halibut may fill a gap between 'enscript' and 'latex' or 'docbook' in that the user may quickly produce a typeset document with 'formatting'. An alternative may be to write a new 'style' for enscript.

Halibut produces nice pdf output, with automatic table of contents and cross-references. It is essentially a 'poor-mans' (and terse) latex

enscript seems to support the halibut format.

pandoc output format (switches -t -w --to --write all equivalent)
native - native haskell format
markdown - markdown syntax
man - unix groff man page
rst - restructured text
html - html
latex - latex typesetting format
docbook - the docbook xml format
opendocument - an xml document format a bit like docbook
mediawiki - the markup used with 'wikipedia'
odt - the open office document format
s5 - an html and javascript slide show format (like powerpoint)
rtf - rich text format for word processors (eg ms word)

halibut output formats
Plain ASCII text
HTML
Unix man page format
GNU info format
PDF
PostScript
Old-style Windows Help (.HLP);

Gotchas ‹↑›

you cant have headings without chapters, etc (its not like html) chapters start new pages and there doesnt seem to be any way around this very few formatting codes in halibut, eg no 'bold' text, or font size I dont think that you can put images in the document

Formatting Examples ‹↑›

display text between quotes

 here is some \q{text in quotes}

format code with some un-line-breakable hyphens and underscores

 the Emacs command \c{M\-x\_psychoanalyze\-pinhead}

halibut codes can be multi-line

  \e{this is
  emphasised}

include an automatically generated date

 This document was generated on \date
the date looks like 'Thu Feb 1 12:20:43 2007'

include an auto-date in a specific format

 This document was generated on \date{%Y-%m-%d %H:%M:%S}
this date looks like '2007-02-01 12:20:43'

view possible date format strings

 man ? strftime

Urls ‹↑›

format a url with the display string 'google'

 Try searching on \W{http://www.google.com/}{Google}.

display a url with itself as the display string

 Google is at \W{http://www.google.com/}\cw{www.google.com}

for pdf output use code formatting for urls, if no link is required

 Try searching on \c{http://www.google.com/}
 Try searching on \cw{http://www.google.com/}   nearly the same

Unicode ‹↑›

include a unicode character in the document

 \u0041   this would display 'A' since 41 is the code for 'A'

include the 'euro' symbol or the text 'EUR_' if the symbol is not available

 This is likely to cost \u20AC{EUR\_}2500 at least.

include a comment in a document, which will be ommited in the output

 The typical behaviour of an antelope \#{do I mean gazelle?} is..

include code in a halibut source document


  \c #include <stdio.h>
  \c
  \c int main(int argc, char **argv) {
  \c     printf("hello, world\n");
  \c     return 0;
  \c }

Chapter And Section Headings ‹↑›

create a title for the whole document

 \title A Simple Car Manual

create a chapter heading 'special tools' with a reference keyword 'tools'

 \C{tools} Special Tools

insert a cross-reference to the tools chapter created above

 see the \k{tools} chapter

create a heading (one level below chapters)

 \H{tool-types} Tool Types

create a section heading (two levels below a chapter)

 \s{sec1} other concerns

create a section which is called a 'question' in the table of contents

 \S{question-about-fish}{Question} What about fish?

create an appendix

 \A

Lists ‹↑›

include a list in a document

  A list follows,

  \b One.

  \b Two.

  \b Three.

format a numbered list

  A list follows,

  \n One.

  \n Two.

  \n Three.

format a list with a reference


  \n One.

  \n{this-one} Two.

  \n Three.

  \n go back to step \k{this-one}.

create a description list


  \dt Pelican

  \dd This is a large bird with a big beak.

  \dt Panda

  \dd This isn't.

create a horizontal rule

 \rule

Cross References ‹↑›

include references or links to document sections

 \K{chap1} expands on \k{chap2}. 'chap1' and 'chap2' are keywords
##(\K starts with a capital letter)

define a bibliography entry

 \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs.
 Published by Paperjam & Notoner, 1993.

refer to a bibliography entry with the \k command

 \k{freds-book}

create a citation to a book

 \nocite{abook}

The Index ‹↑›

create an index entry in a source document

 The \i{hippopotamus} is a particularly large animal.
the index will include the word 'hippo' and the page where is occurs

create a multi-word index entry

 we recommend a \i{torque wrench} for this job.

create an index entry for a code term

 \i\c{grep} command is what you want here.

create an index for a word and emphasise it in the text

 this is what we call a \i\e{paper jam}

create an index entry which doesnt appear in the text

 If your printer runs out of toner, \I{replacing toner cartridge} do this:

Configuring Halibut ‹↑›

For producing pdf or postscript documents, all the margins and other spacings are configurable, using the \cfg command.

www: http://www.chiark.greenend.org.uk/~sgtatham/halibut/doc-1.0/output.html#output-paper
options to configure pdf output
configure something
 \cfg

label all chapters as 'Book'

 \cfg{chapter}{Book}

define a macro

 \define{eur} \u20AC{EUR\_}

use the macro which was just defined

 This is likely to cost \eur 2500 at least.

configure the font size of the document text

 \cfg{paper-base-font-size}{points} Specifies the font size of body text.

other config options

  \cfg{paper-page-height}{points}
      Specify the absolute limits of the paper. 
      \cfg{paper-left-margin}{points}
      \cfg{paper-top-margin}{points}
      \cfg{paper-right-margin}{points}
      \cfg{paper-bottom-margin}{points}
          Specify the margin

Compiling Documents ‹↑›

produce html 'test.html' from the input text file 'file.txt'

 halibut --html=test.html file.txt

create a pdf file 'output.pdf' from the input file 'file.txt'

 halibut --pdf file.txt

Enscript ‹↑›

enscript is the simplest solution for creating a printed document, and such a handy way to quickly get some printed output without wasting precious paper. its great. Enscript may be able to produce postscript and pdf output quickly but it also has many options, which may make more complex typesetting tools unnecessary.

view a postscript file

 gv file.ps
 evince file.ps   nicer than the ancient 'gv'

Basic Usage ‹↑›

The output file, if it exists, is overwritten.

convert plain text 'file.txt' to a pdf file 'output.pdf'

 enscript -p file.ps file.txt; ps2pdf file.ps

create a pdf file from 'file.txt'

 enscript -o - file.txt | ps2pdf - file.pdf

create a postscript document from the '.txt' files in the current folder

 enscript -p output.ps *.txt

create a postscript document from 2 files, each line containing 'honey'

 cat file1.txt file2.txt | grep -v honey | enscript -p output.ps
using this method enscript cant put the filename in the header

Headers And Footers ‹↑›

The header is what is printed at the top of each page of the outputted postscript document.

halibut markup codes (text is placed between the braces)
\e{} emphasize (eg italicize) the text between the braces
\c{} format as code (normally use a fixed-pitch font such as courier)
\cw{} format as weak code
\cq{} format as quoted code
\k{} \K{} a reference to document section heading
\W{http://www.google.com/}{Google} url markup
\i{words} index the words within the braces
\u00F6{oe} embedd a unicode character in the text
\q{} quoted text
\quote{} a long, maybe multi-paragraph quotations
\rule a horizontal rule on the page (should go on a line by itself)
\C \H \S \A \U Chapter and section headings
\title

create a pdf file with no "headers" called "output.pdf"

 enscript -B -p output.ps file.txt; pd2pdf output.ps
 enscript -Bp output.ps file.txt; pd2pdf output.ps   the same
 enscript -Bo - file.txt | pd2pdf - output.ps        the same

create a document with the text 'A summers day' at the top of each page

 enscript -b 'The summers day' -p out.ps file.txt
 enscript --header='The summers day' -p out.ps file.txt   the same

output a document with header as filename, current date, and page numbers

 enscript --header='$n %W Page $% of $=' -p out.ps file.txt
 enscript -b '$n %W Page $% of $=' -p out.ps file.txt

this would print 'out.ps 12/12/2003 Page 2 of 20' or something like that

create a document with a header with 'justified' fields (left, center, right)

 enscript --header='$n|%W|Page $% of $=' -p out.ps file

create a postscript file 'output.ps' with fancy grey headers

 enscript -G -p output.ps list.txt
the header contains the date, file name and the page number

create a ps document with a footer which is like 'Page 2 of 24'

 enscript --footer='Page $% of $=' -p out.ps file.txt

Changing The Font ‹↑›

The text after the '-f' switch has to be a valid font specification,

show all valid font names which can be used with the enscript -f option

 less /usr/share/enscript/afm/font.map   your mileage may vary
 find / -name 'font.map'    if the above didnt work

create a postscript file "new.ps" using the font "Helvetica12"

 enscript -f "Helvetica12" -p new.ps file.txt
 enscript -f "Helvetica@12" -p new.ps file.txt   the same
 enscript -fHelvetica12 -p new.ps file.txt  this seems to work as well

these font names are case sensitive!!

 enscript -f "helvetica12" -p new.ps file.txt

create a postscript document using 8.5 point Times-Roman font

 enscript -f 'Times-Roman8.5' -p new.ps file.txt
 enscript -f 'Times-Roman@8.5' -p new.ps file.txt  should be the same

create a document using a font which is 10 points wide and 14 points high

 enscript -f 'Courier@10/14' -p new.ps file.txt

create a postscript file with a smaller font

 enscript -f "Helvetica8" -p new.ps file.txt
 enscript -f "Helvetica6" -p new.ps file.txt  only 6 points!
 enscript -f "Helvetica4" -p new.ps file.txt  tiny, need a good printer

Creating Banner Text With Enscript ‹↑›

www: http://www.linux.com/archive/articles/55835
how to make 'web banners' (an image to go at the top of a webpage) using enscript, by Michael Stutz, the same guy who wrote the Linux Cookbook for No Starch Press.
make a large image of the text 'Green Tree'
 echo "Green Tree" | enscript -B -f "Palatino-Bold48" -o blog.ps
 echo "Green Tree" | enscript -Bf "Palatino-Bold48" -p blog.ps same

do the whole thing in imagemagick

 convert -font Helvetica-Bold -pointsize 48 -background black -fill red label:'Hallo world' allo.png

crop out all the unnecessary space around the text and convert to 'jpg'

 convert -crop WxH+0+0 filename.ps filename.jpg  width and height
 convert -trim +repage filename.ps filename.jpg  untested

all in one go

 echo "Headlines for `date +'%B %e'`" | enscript -o - -B -f "Times-Bold48" | convert -crop 200x600+0+0 - headlines.png  untested

Multiple Columns ‹↑›

change the horizontal column height

 --h-column-height=height

make a postscript file (from 2 text files) with 3 columns, and view it.

 cat file1.txt file2.txt | enscript -3p output.ps; evince output.ps

create a 2 column postscript file with lines separating columns and a frame

 enscript -2 -j -p file.ps file.txt
 enscript -2jp file.ps file.txt    the same, but better

create a pdf document with 20 columns and no 'headers' (thats right, 20)

 enscript --columns=20 -2Bp file.ps file.txt; ps2pdf file.ps
the 'header' is the text which appears at the top of each page

create a postscript document 'new.ps' with 9 columns from 'file.txt'

 enscript -9p new.ps file.txt

Landscape Printing ‹↑›

convert "file.txt" to pdf "file.pdf" landscape format with 2 columns

 enscript -2r -p file.ps file.txt; ps2pdf file.ps

Changing The Margins ‹↑›

set the margins in the document to those specified

 enscript --margins=50:50:50:100 -p tree.ps tree.txt

In my version of enscript 1.6.4 the format for the margin command is

 --margins=top:bottom:right:left which is a very unusual order

but in the documentation the format is stated to be

 --margins=top:bottom:right:left which would be more logical

set the left and right margins to 50 pnts with top and bottom default

 enscript --margins=50:50 -p tree.ps tree.txt

indent every line by 2 character widths

 enscript -i 2l     2 character widths
 enscript -i 20p    indent by 20 points
 enscript -i 3i     3 inches
 enscript -i 3c     3 centimetres

Underlayed Text ‹↑›

Enscript can print an 'underlayed' text which is like a watermark which goes underneath the text from the file.

create a postscript file with a "watermark" large font text diagonally down the page.

 enscript -u"Resume" -p file.ps file.txt

Output Formats ‹↑›

Instead of creating postscript files, enscript can also create 'rtf' (rich text format) files (which can be opened in Microsoft Word, for example) and 'html' files, which can be viewed with a web-browser such as 'google chrome', 'firefox' or 'internet explorer'.

create a rich text file 'output.rtf' from a text file with no headers

 enscript -wrtf -B -p output.rtf file.txt
rtf files can be opened in wysiwyg editors like MS Word

create a colourised webpage of the file "tree.txt"

 enscript -whtml --color -E -p file.html tree.txt

Changing The Printout ‹↑›

make a pdf file 'output.pdf' with each line preceded by the line number

 enscript --line-numbers -p output.ps list.txt; ps2pdf output.ps
 enscript -Cp output.ps list.txt; ps2pdf output.ps  the same

create a document with each line numbered starting at line 20

 enscript -C20 -p output.ps list.txt

The Page Size ‹↑›

show what page sizes enscript can output to

 enscript --list-media

create a postscript document with an 'A5' page size

 enscript -M A5 -p out.ps file.txt
 enscript --media=A5 -p out.ps file.txt   the same

Making Booklets ‹↑›

By using the 'N-up' printing facilities of enscript it should be possible to create 'booklets', that is, postscript documents which when printed out and folded in half, have all the pages in the right place (just like a real book; this is also called 'quires'). N-up printing involves putting a multiple of 2 logical pages on each physical page.

put 2 logical pages on each physical page

 enscript -U2 -p out.ps file.txt
 enscript -nup=2 -p out.ps file.txt  the same

put 4 logical pages on each page

 enscript -U4 -p out.ps file.txt

other nup options which may do what we need

--nup-columnwise Change the layout of the sub-pages in the N-up printing from row- wise to columnwise. --nup-xpad=num Set the page x-padding of the n-up printing to num PostScript points. The default is 10 points. --nup-ypad=num Set the page y-padding of the n-up printing to num PostScript points. The default is 10 points. ,,,

Printing Code ‹↑›

Enscript can be used to provide nice listing of software 'code'.

show what code languages enscript can pretty-print

 enscript --help-highlight | grep 'Name:' | less
 enscript --help-highlight | less show more detailed information

create a colourised webpage of the file "Point.java" with syntax highlighting

 enscript -whtml --color -E -p file.html Point.java

print a gaudy header, two columns, landscape, code highlighting, 2-up printing.

  enscript -G2rE -U2 foo.c

when a line is too long and must be wrapped print an arrow at the line end

 enscript --mark-wrapped-lines=arrow -p output.ps list.txt

 --mark-wrapped-lines={plus|box|arrow}

Other Plain Text Documentation Systems ‹↑›

This book tries to elucidate the forest of different ways and formats in which to write text documentation and the software which is used to transform the text into other digital formats and printed documents.

commandlinefu.com

Man Pages ‹↑›

man: software <man>ual pages

Man ('manual') pages is the traditional Unix documentation format. The man page format is a simple plain text format using macros for the troff or groff document system. The Man documentation system is specifically designed for documenting software.

www: http://www.schweikhardt.net/man_page_howto.html
links to documents by Kernighan ...
www: http://babbage.cs.qc.edu/courses/cs701/Handouts/man_pages.html

Viewing Man Pages ‹↑›

viewing a man page with 'man' (the normal way to view a man page)

 man program   the file program.n must be in the manpath

viewing the bobble manpage with groff (useful when writing a man page)

 groff -man -Tascii bobble.1 | less
 groff -man -Tutf8 bobble.1 | less

viewing the 'bobble' program man page with nroff

 nroff -man bobble.1 | less

view the raw groff text for the 'bobble' program man page.

 zless .../man/man1/bobble.1.gz   if the pages are compressed
 less .../man/man1/bobble.1       if the pages are not compressed
useful to learn how to write a man page.type 'manpath' to find the path to the manpages

other viewing tools are xman, tkman, info

Writing Man Pages ‹↑›

see the conventions for writing a man page

 man 7 man

see the formatting codes available

 man groff_man

o- - decide what section the page should go in (see:man page sections) - write the man page - name the file 'name.n' where 'n' is the section - place the file in .../man/manN/ where 'N' is the section (same as above) - if the page is not written in english, place the file in the folder .../man/aa/manN/ where 'aa' is a language or locale code, for example 'fr' for french, or 'es' for spanish. and 'N' is the section. -

Man Formatting Conventions ‹↑›

While the author of a unix man page is free to format the document as she feels fit, certain conventions are time-tested and true.

In the synopsis section use bold alternating with italic for functions

 .BI "myfunction(int " argc ", char **" argv );

file names in italic outside of the 'synopsis' section

 .I /usr/include/stdio.h

in the synopsis section, make file names bold

 .B #include <stdio.h>

put references to other man pages in bold alternating with roman

 .BR man (7)

format acronymns in a small font

 .SM UNIX

summarize command options with .IP

 .IP -b

Man Formatting Codes ‹↑›

view the man macro help for a list of formatting codes

 man groff_man  as usual, this contains no examples

create a document title

  .TH FOO 1 "MARCH 2003" Linux "User Manuals"
command name: foo, section: 1 (user commands ) last revision: march 2003, other title: Linux ...

section heading

  .SH heading

subsection headings

  .SS heading

display a sentence in italics

  .I "some words"

put the word 'type' in italics

 /fItype/fP       groff codes

insert preformatted text in a man page (using groff requests)

      .nf
        pre formatted text ...
      .fi

begin a new paragraph

 .PP

indent an option list with .TP (the first line after .TP is the label)

>

Tp ‹↑›

\-h display a short help text

Tp ‹↑›

\-d use the given device <<< .TP has the advantage over .IP that the paragraph label can be formatted

hanging left indented paragraph

 .HP

indented paragraph with label

  .IP label

this can be used for summarizing options etc. If the label is long then the indented paragraph is begun on a new line (definition list style) other wise the indented paragraph is begun on the same line. (table style)

example: .IP -b turn on debug mode .IP "-config file" load the specifed config file --;

indent the following text by the default amount

 .RS

indent the following text by 10

 .RS 10

stop indenting text

 .RE stop indenting

Standard Man Page Document Sections ‹↑›

a comment with the groff command

>
.\" Process this file with .\" groff -man -Tascii foo.1 .\" <<<

the title of the document

 .TH FOO 1 "MARCH 1995" Linux "User Manuals"

name, the name of the command etc

>

Sh Name ‹↑›

boggle \- frobnicate the bar library <<<

synopsis, summary of the command usage

>

Sh Synopsis ‹↑›

.B boggle [-bar] [-c .I config-file .B ] .I file

B ‹↑›

<<<

description, a complete description of what the command does

   
      .SH DESCRIPTION
      .B boggle 
      frobnicates the bar library by tweaking internal
      symbol tables. By default it parses all baz segments
      and rearranges them in reverse order by time for the
      .BR xyzzy (1)
      linker to find them. The symdef entry is then compressed
      using the WBG (Whiz-Bang-Gizmo) algorithm.
      All files are processed in the order specified.

options, the options which the command accepts


      .\" this could be formatted with a .TP list as well
      .SH OPTIONS
      .IP -b
      Do not write `busy' to stdout while processing.
      .IP "-c config-file"
      Use the alternate system wide
      .I config-file
      instead of
      .IR /etc/foo.conf .

files, other files which the command uses (a .TP list could be used)

>
.I /etc/foo.conf

Rs ‹↑›

The system wide configuration file. See .BR foo (5)

Re ‹↑›

.I ~/.foorc

Rs ‹↑›

Per user configuration file. <<<

environment, any environment variables which affect the program

>

Ip Fooconf ‹↑›

If non-null the full pathname for an alternate system wide .IR foo.conf . Overridden by the .B -c option. <<<

diagnostics, messages which the program may display


       .SH DIAGNOSTICS
       The following diagnostics may be issued on stderr:
       Bad magic number.
       .RS
       The input file does not look like an archive file.
       .RE
       Old style baz segments.
       .RS
       .B foo
       can only handle new style baz segments. COBOL
       object libraries are not supported in this version.

bugs, problems with the program

      .SH BUGS
      The command name should have been chosen more carefully
      to reflect its purpose.

author

>

Sh Author ‹↑›

bob good <who at server dot net> <<<

see also, other programs or documents relevant to this one.

>
.SH "SEE ALSO" .BR bar (1), .BR boggle (5), <<<

Standard Location Of Man Pages ‹↑›

Man pages should be placed in their appropriate section (subfolder) and with the correct extension

www: http://www.schweikhardt.net/man_page_howto.html
a man page howto with links to all the manuals
see where the 'man' command searches for man pages
 manpath

file name and location of the user command 'boggle' man page

 .../man/man1/boggle.1
 .../man/man1/boggle.1.gz  man pages can be compressed as well
the file boggle.1 is a plain text file

file name and location of the man page for the library function 'doogle'

 .../man/man3/doogle.3

location of the man page written in french for the library function 'doogle'

 .../man/fr/man3/doogle.3

search for man pages in 'folder' instead of in 'manpath'

 man -M folder boggle
useful while writing and testing man pages

special enscript header/footer codes
$$ - character '$'
$% - current page number
$= - number of pages in the current file
$p - number of pages processed so far
$(VAR) - value of the environment variable VAR.
%c - trailing component of the current working directory
%C - ($C) current time (file modification time) in 'hh:mm:ss' format
%d - current working directory
%D - ($D) current date (file modification date) in 'yy-mm-dd' format
%D{string} - ($D{string}) '%D{}' refers to the current date and `$D{}' to the input file's last modification date.
%E - ($E) current date (file modification date) in 'yy/mm/dd' format
%F - ($F) current date (file modification date) in 'dd.mm.yyyy'
%H - document title
$L - number of lines in the current input file. This is valid strings.
%m - the hostname up to the first '.' character
%M - the full hostname
%n - the user login name
$n - input file name without the directory part
%N - the user's pw_gecos field up to the first '' character
$N - the full input file name
%t - current time in 12-hour am/pm
$t - file modification time in 12-hour am/pm
%T - current time in 24-hour format
$T - file modification time in 24-hour format
%* - ($*) current time (file modification time) in 24-hour format
$v - the sequence number of the current input file
%W - ($W) current date (file modification date) in 'mm/dd/yy' format

automatically generate man pages from C, C++, Java, Python ... source code

 doxygen   doxygen can also generate documentation in html, latex etc

a cgi script for generating html man pages

 man2html

Converting Man Pages To Other Formats ‹↑›

convert the 'doogle.1' man page to html

 man2html doogle.1

convert to html using groff

 groff -Thtml /path/to/manpage.n

rman can convert to latex, rtf, sgml, html, ...

 rman

convert the 'ls' manpage to plain text, converting tabs to spaces (-x)

 man ls | col -bx | less

convert a man page to postscript

 groff -man -Tps /path/to/manpage.n

convert a man page to dvi

 groff -man -Tdvi /path/to/manpage.1

convert a man page to pdf

 man -Tps ls | ps2pdf - ls_man.pdf

Converting To Man Pages From Other Formats ‹↑›

convert a perl documentation doc (pod) to a man page

 pod2man bogg.pod > bogg.1

Groff And Troff ‹↑›

Troff: <T>ypesetting <R>un <Off> system Groff:

Groff is the Gnu version of the Troff document formatting and typesetting system, which was maintained for many years by Kernighan

www: http://www.kohala.com/start/troff/troff.html
a list of resources and documents for troff

Using Tables ‹↑›

use the tbl macros

Diagrams And Pictures With Groff ‹↑›

Creating certain sorts of diagrams with groff can be achieved with the 'pic' preprocessor.

http://www.kohala.com/start/troff/cstr116.ps Brian Kernighans manual for pic

http://www.kohala.com/start/troff/gpic.raymond.ps A manual for gpic the gnu version of 'pic'

view the help for the 'pic' diagram generator

 man gpic

convert a pic diagram to postscript

 groff -e -p -ms pic.ms > file1.ps

Mathematical Equations ‹↑›

use the 'eqn' macros

Texinfo ‹↑›

Texinfo is the official documentation system of the Free Software Foundation.

Docbook ‹↑›

Docbook is an XML based documentation system

Halibut ‹↑›

www: http://www.chiark.greenend.org.uk/~sgtatham/halibut/
o- halibut, uses a terse plain text input format - the output formats for halibut are: (:Plain ASCII text, HTML, Unix man page format, GNU info format, PDF, PostScript, Old-style Windows Help (.HLP); - not fully unicode

manual page sections
1 user commands executable from a shell
2 kernel system calls
3 library functions and calls (such as libc)
4 special files such as in /dev
5 file formats and conventions (such as /etc/password)
6 games
7 conventions and miscellaneous, file system layout.
8 system management commands such as like mount(8)
9 kernel routines. this is an obsolete manual section.

Source Code Documentation Systems ‹↑›

Doxygen ‹↑›

Javadoc ‹↑›

Javadoc is the document system for the Java programming language. The output format for javadoc is normally HTML

pod perl documentation

DOCUMENT-NOTES:

halibut input format, (text is placed between the braces)
\e{} emphasis
\c{} code
\cw{} weak code
\cq{} quoted code
\W{http://www.google.com/}{Google} url markup