md2texi

Convert nodejs API documentation to the Texinfo format (& subsequently to pdf, html, info).

Prebuilt versions of the current branch (texi, info, html, pdf): http://gromnitsky.users.sourceforge.net/js/nodejs/ (I update them more or less regularly.)

Why?

Read API docs in Emacs.
Indices. Press i in Emacs (or standalone info(1)) and type a function name or whatever.

Optional goodies:

An offline mode.
A nice looking pdf.
A full text search.
An alternate html representation (for example, as a one big file).

Warning: although md2texi may be used as a universal markdown-to-texinfo converter, it was written specifically to support nodejs api doc files.

Requirements

Installed nodejs 6.x
Cloned nodejs repo
texinfo 6.3+
GNU make

Installation

Clone nodejs repo.
Clone md2texi repo, cd to its dir & type npm install.
Create a tmp dir somewhere & cd to it.

Type

 $ make -f ~/tmp/md2texi/main.mk DATA=~/tmp/node/doc/api info

nodejs.info file must appear.

Test the file via info -f ./nodejs.info (yes, ./ is important)
Type
```
 $ make -f ~/tmp/md2texi/main.mk DATA=~/tmp/node/doc/api install
```
to install nodejs.info (it defaults to ~/share/info/) & auto-create a special dir file.

You may get warnings like @ref reference to nonexistent node 'foo_bar' during the compilation. This is not (hehe) a bug in md2texi, but typos in nodejs docs.

Usage

$ md2texi -h

  Usage: md2texi [options] [file.markdown, ...]

  Options:

	-h, --help              output usage information
	-V, --version           output the version number
	-v, --verbose           Be verbose
	-t, --title <string>    Document title
	-a, --author <string>   Document author
	--info-cat <string>     Info category
	-p, --plugins <string>  A list of plugins to use, separated by commas
	--info <string>         Info filename output (for multiple src only)

PDF

If you have texlive & texinfo-tex installed, try to run:

$ make -f ~/tmp/md2texi/main.mk DATA=~/tmp/node/doc/api pdf

to generate nodejs.pdf file.

Bugs

Vintage box drawing chars (┌,┐,└,┘,&c) aren't visible in the pdf output. This is an internal texinfo limitation.
Cross-references in Emacs Info mode are always prefixed w/ the 'see' word, like this: For example a (see request to an HTTP server) is a stream.

To remove the annoying prefix, add this 2 lines to your .emacs file. Beware that other docs (hand-written in Texinfo format) were produced w/ the expectation that the word 'see' is always inserted.
```
 (setq Info-hide-note-references 'hide)
 (setq Info-refill-paragraphs t)
```
Evaluate each line (C-x C-e), kill the Info buffer & open it again.
Tables look fine in the html output but horrific in the info output. This is an Emacs bug.

License

MIT.

EchoAbstract/md2texi