% latex generated by the script '/home/project-web/bumble/cgi-bin/text2latex.cgi' % with help from the sed script 'text2latex.sed' % query string: 'books/linux-document/linux-document-book' % sFileName= 'linux-document-book' % sDirName = 'books/linux-document' % sName = '' --> % latex by http://bumble.sourceforge.net/scripts/text2latex.sed % this script is a work in progress \documentclass[11pt]{article} \usepackage[hmargin=2cm, vmargin=2cm]{geometry} \usepackage{url} \usepackage{hyperref} \begin{document} \\&\\& Writing and Publishing with Linux ------------------------------------, 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' @@ \url{http://daringfireball.net/projects/markdown/} details about the format of the source document (text file). @@ \url{http://daringfireball.net/projects/markdown/dingus} a page to actually try out markdown text syntax @@ \url{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 '';markdown doc.txt;echo '') > out.html >> markdown doc.txt|sed '1s/\\^//;\\$s.\\$..' > 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 \title{=========} \author{bumble.sourceforge.net} \maketitle \tableofcontents ,,, * 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/[ ]*\\$// \\$\\backslash\\$| s/[ ]*\\$// \\$\\backslash\\$| s/[\\^ ]/-/g \\$\\backslash\\$| s/- \texttt{/--/go} \\#\\#(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/[ ]*\\$// \\$\\backslash\\$| s/[ ]*\\$// \\$\\backslash\\$| s/[\\^ ]/=/g \\$\\backslash\\$| s/= \texttt{/==/go} \\#\\#(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)

...

,,, \\#\\#(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 example link.

) * 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]: \url{http://www.google.com} "Google" [2]: \url{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]: \url{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]: \texttt{/path/to/img.jpg} "Title" ,,, EMBEDDED CODE .... * use backticks '`' to show code with special characters in it >> dont use the `` tag * another example >> html entities can be named `\\—` or numbered `\\&\\#8212;`. * use 4 spaces or 1 tab of indentation to display a paragraph of code * use a backslash to escape special characters >> \\$\\backslash\\$* \\#\\#(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 @@ johnmacfarlane.net/pandoc/README an example of a pandoc markdown document @@ johnmacfarlane.net/pandoc/README.html\\#pandocs-markdown-vs.standard-markdown details about the pandoc extensions to the markdown syntax * create subscripts and superscripts >> H\\$\\verb|~|2\\$\\verb|~|O is a liquid. 2\\^10\\^ is 1024. * create text P with 'a cat' superscripted >> P\\$\\verb|~|a\\$\\backslash\\$ cat\\$\\verb|~| \\#\\#(note the escaped backslash in the superscript) * format text which is 'struck out', that is, has a bar through it >> This \\$\\verb|~|\\$\\verb|~|is deleted text.\\$\\verb|~|\\$\\verb|~| * create compact definition lists --------------------------------- Term 1 \\$\\verb|~| Definition 1 Term 2 \\$\\verb|~| Definition 2a \\$\\verb|~| 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 '\\$\\verb|~|' characters) ----------------------------------------------------------------- \\$\\verb|~|\\$\\verb|~|\\$\\verb|~| code \\$\\verb|~|\\$\\verb|~|\\$\\verb|~| ,,, * source code blocks with syntax highlighting and numbered lines ---------------------------------------------------------------- \\$\\verb|~|\\$\\verb|~|\\$\\verb|~|\\$\\verb|~|\\$\\verb|~|\\$\\verb|~|\\$\\verb|~| \{.haskell .numberLines\} qsort [] = [] qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ qsort (filter (>= x) xs) \\$\\verb|~|\\$\\verb|~|\\$\\verb|~|\\$\\verb|~|\\$\\verb|~|\\$\\verb|~|\\$\\verb|~| ,,, 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 ---------------------------------------

*one*

[a link](http://google.com)

,,, * 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. @@ \url{http://johnmacfarlane.net/pandoc/README.html} the good user guide for pandoc @@ \url{http://johnmacfarlane.net/pandoc/examples.html} example of converting markdown (et al) documents to other formats @@ \url{http://groups.google.com/group/pandoc-discuss} the pandoc discussion news group \title{} \author{bumble.sourceforge.net} \maketitle \tableofcontents 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. .. 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. \title{} \author{bumble.sourceforge.net} \maketitle \tableofcontents 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) .. 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 \url{http://www.gnu.org/software/make/} -o eg.text HALIBUT @@ \url{http://www.chiark.greenend.org.uk/\\$\\verb|~|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. \title{} \author{bumble.sourceforge.net} \maketitle \tableofcontents halibut output formats .. Plain ASCII text, .. HTML, .. Unix man page format, .. GNU info format, .. PDF, .. PostScript, .. Old-style Windows Help (.HLP); .. \title{} \author{bumble.sourceforge.net} \maketitle \tableofcontents halibut markup codes (text is placed between the braces) .. \\$\\backslash\\$e\{\}, emphasize (eg italicize) the text between the braces .. \\$\\backslash\\$c\{\}, format as code (normally use a fixed-pitch font such as courier) .. \\$\\backslash\\$cw\{\}, format as weak code .. \\$\\backslash\\$cq\{\}, format as quoted code .. \\$\\backslash\\$k\{\} \\$\\backslash\\$K\{\}, a reference to document section heading .. \\$\\backslash\\$W\{http://www.google.com/\}\{Google\}, url markup .. \\$\\backslash\\$i\{words\}, index the words within the braces .. \\$\\backslash\\$u00F6\{oe\}, embedd a unicode character in the text .. \\$\\backslash\\$q\{\}, quoted text .. \\$\\backslash\\$quote\{\}, a long, maybe multi-paragraph quotations .. \\$\\backslash\\$rule, a horizontal rule on the page (should go on a line by itself) .. \\$\\backslash\\$C \\$\\backslash\\$H \\$\\backslash\\$S \\$\\backslash\\$A \\$\\backslash\\$U , Chapter and section headings .. \\$\\backslash\\$title .. 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 \\$\\backslash\\$q\{text in quotes\} * format code with some un-line-breakable hyphens and underscores >> the Emacs command \\$\\backslash\\$c\{M\\$\\backslash\\$-x\\$\\backslash\\$\\_psychoanalyze\\$\\backslash\\$-pinhead\} * halibut codes can be multi-line --------------------------------- \\$\\backslash\\$e\{this is emphasised\} ,,, * include an automatically generated date >> This document was generated on \\$\\backslash\\$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 \\$\\backslash\\$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 \\$\\backslash\\$W\{http://www.google.com/\}\{Google\}. * display a url with itself as the display string >> Google is at \\$\\backslash\\$W\{http://www.google.com/\}\\$\\backslash\\$cw\{www.google.com\} * for pdf output use code formatting for urls, if no link is required >> Try searching on \\$\\backslash\\$c\{http://www.google.com/\} >> Try searching on \\$\\backslash\\$cw\{http://www.google.com/\} \\#\\#(nearly the same) UNICODE .... * include a unicode character in the document >> \\$\\backslash\\$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 \\$\\backslash\\$u20AC\{EUR\\$\\backslash\\$\\_\}2500 at least. * include a comment in a document, which will be ommited in the output >> The typical behaviour of an antelope \\$\\backslash\\$\\#\{do I mean gazelle?\} is.. * include code in a halibut source document ------------------------------------------- \\$\\backslash\\$c \\#include \\$\\backslash\\$c \\$\\backslash\\$c int main(int argc, char **argv) \{ \\$\\backslash\\$c printf("hello, world\\$\\backslash\\$n"); \\$\\backslash\\$c return 0; \\$\\backslash\\$c \} ,,, CHAPTER AND SECTION HEADINGS .... * create a title for the whole document >> \\$\\backslash\\$title A Simple Car Manual * create a chapter heading 'special tools' with a reference keyword 'tools' >> \\$\\backslash\\$C\{tools\} Special Tools * insert a cross-reference to the tools chapter created above >> see the \\$\\backslash\\$k\{tools\} chapter * create a heading (one level below chapters) >> \\$\\backslash\\$H\{tool-types\} Tool Types * create a section heading (two levels below a chapter) >> \\$\\backslash\\$s\{sec1\} other concerns * create a section which is called a 'question' in the table of contents >> \\$\\backslash\\$S\{question-about-fish\}\{Question\} What about fish? * create an appendix >> \\$\\backslash\\$A LISTS .... * include a list in a document ------------------------------ A list follows, \\$\\backslash\\$b One. \\$\\backslash\\$b Two. \\$\\backslash\\$b Three. ,,, * format a numbered list ------------------------ A list follows, \\$\\backslash\\$n One. \\$\\backslash\\$n Two. \\$\\backslash\\$n Three. ,,, * format a list with a reference -------------------------------- \\$\\backslash\\$n One. \\$\\backslash\\$n\{this-one\} Two. \\$\\backslash\\$n Three. \\$\\backslash\\$n go back to step \\$\\backslash\\$k\{this-one\}. ,,, * create a description list --------------------------- \\$\\backslash\\$dt Pelican \\$\\backslash\\$dd This is a large bird with a big beak. \\$\\backslash\\$dt Panda \\$\\backslash\\$dd This isn't. ,,, * create a horizontal rule >> \\$\\backslash\\$rule CROSS REFERENCES .... * include references or links to document sections >> \\$\\backslash\\$K\{chap1\} expands on \\$\\backslash\\$k\{chap2\}. \\#\\#('chap1' and 'chap2' are keywords) \\#\\#(\\$\\backslash\\$K starts with a capital letter) * define a bibliography entry >> \\$\\backslash\\$B\{freds-book\} \\$\\backslash\\$q\{The Taming Of The Mongoose\}, by Fred Bloggs. >> Published by Paperjam \\& Notoner, 1993. * refer to a bibliography entry with the \\$\\backslash\\$k command >> \\$\\backslash\\$k\{freds-book\} * create a citation to a book >> \\$\\backslash\\$nocite\{abook\} THE INDEX .... * create an index entry in a source document >> The \\$\\backslash\\$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 \\$\\backslash\\$i\{torque wrench\} for this job. * create an index entry for a code term >> \\$\\backslash\\$i\\$\\backslash\\$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 \\$\\backslash\\$i\\$\\backslash\\$e\{paper jam\} * create an index entry which doesnt appear in the text >> If your printer runs out of toner, \\$\\backslash\\$I\{replacing toner cartridge\} do this: CONFIGURING HALIBUT .... For producing pdf or postscript documents, all the margins and other spacings are configurable, using the \\$\\backslash\\$cfg command. @@http://www.chiark.greenend.org.uk/\\$\\verb|~|sgtatham/halibut/doc-1.0/output.html\\#output-paper options to configure pdf output * configure something >> \\$\\backslash\\$cfg * label all chapters as 'Book' >> \\$\\backslash\\$cfg\{chapter\}\{Book\} * define a macro >> \\$\\backslash\\$define\{eur\} \\$\\backslash\\$u20AC\{EUR\\$\\backslash\\$\\_\} * use the macro which was just defined >> This is likely to cost \\$\\backslash\\$eur 2500 at least. * configure the font size of the document text >> \\$\\backslash\\$cfg\{paper-base-font-size\}\{points\} Specifies the font size of body text. * other config options ---------------------- \\$\\backslash\\$cfg\{paper-page-height\}\{points\} Specify the absolute limits of the paper. \\$\\backslash\\$cfg\{paper-left-margin\}\{points\} \\$\\backslash\\$cfg\{paper-top-margin\}\{points\} \\$\\backslash\\$cfg\{paper-right-margin\}\{points\} \\$\\backslash\\$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. \title{} \author{bumble.sourceforge.net} \maketitle \tableofcontents 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 .. * 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 \texttt{/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 .... @@ \url{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 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. @@ \url{http://www.schweikhardt.net/man\\_page\\_howto.html} links to documents by Kernighan ... @@ \url{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 \begin{enumerate} \item \item decide what section the page should go in (see:man page sections) \item write the man page \item name the file 'name.n' where 'n' is the section \item place the file in .../man/manN/ where 'N' is the section (same as above) \item 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. \item \end{enumerate} 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 \texttt{/usr/include/stdio.h} * in the synopsis section, make file names bold >> .B \\#include * 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 >> \texttt{/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 \\$\\backslash\\$-h display a short help text .TP \\$\\backslash\\$-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 >>> .\\$\\backslash\\$" Process this file with .\\$\\backslash\\$" groff -man -Tascii foo.1 .\\$\\backslash\\$" <<< * the title of the document >> .TH FOO 1 "MARCH 1995" Linux "User Manuals" * name, the name of the command etc >>> .SH NAME boggle \\$\\backslash\\$- 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 ------------------------------------------------ .\\$\\backslash\\$" 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 \texttt{/etc/foo.conf} . ,,, * files, other files which the command uses (a .TP list could be used) >>> .I \texttt{/etc/foo.conf} .RS The system wide configuration file. See .BR foo (5) .RE .I \\$\\verb|~|/.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 <<< * 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 @@ \url{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) \title{} \author{bumble.sourceforge.net} \maketitle \tableofcontents 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 \texttt{/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. .. * 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 \texttt{/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 \texttt{/path/to/manpage.n} * convert a man page to dvi >> groff -man -Tdvi \texttt{/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: ypesetting un system Groff: Groff is the Gnu version of the Troff document formatting and typesetting system, which was maintained for many years by Kernighan @@ \url{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. \url{http://www.kohala.com/start/troff/cstr116.ps} Brian Kernighans manual for pic \url{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 ----------------------------------------------------------- @@ \url{http://www.chiark.greenend.org.uk/\\$\\verb|~|sgtatham/halibut/} \begin{enumerate} \item halibut, uses a terse plain text input format \item the output formats for halibut are: (:Plain ASCII text, HTML, Unix man page format, GNU info format, PDF, PostScript, Old-style Windows Help (.HLP); \item not fully unicode \end{enumerate} \title{} \author{bumble.sourceforge.net} \maketitle \tableofcontents halibut input format, (text is placed between the braces) .. \\$\\backslash\\$e\{\}, emphasis .. \\$\\backslash\\$c\{\}, code .. \\$\\backslash\\$cw\{\}, weak code .. \\$\\backslash\\$cq\{\}, quoted code .. \\$\\backslash\\$W\{http://www.google.com/\}\{Google\}, url markup .. 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: \\# this section contains information about the document and \\# will not normally be printed. \\# A small (16x16) icon image to identify the book document-icon: \texttt{/img/icon/book-open.png} \\# A larger image to identify or illustrate the title page document-image: \\# what sort of document is this document-type: book \\# in what kind of state (good or bad) is this document document-quality: not very good \\# when was this document last updated last-revision: oct 2009 \\# who wrote this authors: mjb \\$\\verb|~| \url{http://bumble.sourceforge.net} \\# a short description of the contents, possible used for doc lists short-description: A book about generating documentation in various formats \\# the script which will be used to produce html (a webpage) make-html: ./book-html.sh \\# the script which will produce 'LaTeX' output (for printing, pdf etc) make-latex: DOCUMENT-NOTES: \\# this section contains information about the document and \\# will not normally be printed. \\# A small (16x16) icon image to identify the book document-icon: \\# A larger image to identify or illustrate the title page document-image: \\# what sort of document is this document-type: book \\# in what kind of state (good or bad) is this document document-quality: begun \\# when was this document last updated last-revision: \\# who wrote this document-history: @@ 27 march 2010 This document was begun since sufficient information was available about various documentation systems such as markdown in the 'linux-book.txt'. This was combined with an earlier 'doc-systems-book.txt' @@ date work description \\# who wrote this authors: mjbishop@utas.edu.au \\# a short description of the contents, possible used for doc lists short-description: writing and typesetting in linux \\# A computer language which is contained in the document, if any code-language: bash \\# the script which will be used to produce html (a webpage) make-html: ./? \\# the script which will produce 'LaTeX' output (for printing, pdf etc) make-latex: ./? \end{document} %end generated latex