sitaramc / git-notes

# (READ THIS FIRST) README for the git-notes repo
This repo contains all my notes about git.  I started writing them for my
own understanding, almost like cheat sheets, but they may be useful for others
also.
See 000-README.notes (or 000-README.html in the generated pages) for details
of what these files contain.
The rest of this readme is only about the markup that I use; from a
git-learning point of view this is administrivia.
----
[[TOC]]
## Reading these files
All these documents are plain text, so reading them as is should be no problem
using any text editor/viewer.
#### HTML and PDF
If you want to format them to HTML
  * first, use the `md.pl` program inside the `tools` subdirectory.  This
    handles superscript tags (two `^` characters on each side) to
    `<sup>..</sup>` pairs, and includes a proper TOC if the `[[TOC]]` marker
    is found.
    This produces proper *Markdown* text.  You can also give it the `-css`
    option is you want a small amount of CSS at the top (highly recommended).
  * then, use the standard `Markdown.pl` program (a copy can be found in the
    same `tools` subdirectory) to convert *Markdown* to *HTML*.
You can convert the HTML to PDF by piping it to `html2ps | ps2pdf - - >
output.pdf`.
## Updating the content
  * Please continue to use the ".notes" extension for these files.  Some parts
    of my automated workflow (not part of this repo) use this to identify
    which files to pre-process using `md.pl`.
  * Please do not use hard tabs.
  * If you wish to send me patches, please use Markdown markup.  The
    "extensions" I use should not bother you too much, (unlike in the old
    wiki_creole days).
  * Please note that I consider HTML and PDF to be generated outputs, so they
    are listed in ".gitignore".
#### Generating a TOC
If the token `[[TOC]]` appears on a line by itself, `md.pl` will generate a
table of contents for all headings upto level 4 and insert it at that
position.  You can change that to some other level, say 3, by saying "TOC 3"
instead of just TOC.