Beej's Guide to Network Programming source markdown

Beej' extensions to markdown

These are brought to life with the bin/preproc script.

• [[pagebreak]]

  Issue a page break on the printed version. Renders as LaTeX \newpage.

• [nh[word]]

  Don't allow hypenation of this word. Translates to \hyphenation{word}. Underscores are prohibited due to LaTeX restrictions.

• [ix[entry]]

  Build a LaTeX index entry, substituting it as-is into an \index{} element. Remember to escape your underscores with \_ in these entries! LaTeX indexing examples here.

• [ixtt[entry]]

  For a single, simple index entry, renders in typewriter text with \index{entry@\texttt{entry}}. More complex entries should be rendered by passing raw LaTeX into [ix[]].

• [fl[linktext|url]]

  Footnote Link. Hyperlink linktext to the url and show the URL in a footnote. Translates to [linktext](url)^[url].

• [flx[linktext|file]]

  Footnote Link to Beej's Examples. Automatically prepends https://beej.us/guide/bgnet/examples/ to the file and shows the URL in a footnote.

• [flr[link|id]]

  Footnote Link to Beej's Redirect. Automatically prepends https://beej.us/guide/url/ to the link id and shows the URL in a footnote.

• [flrfc[link|num]]

  Footnote Link to RFC. Automatically prepends https://tools.ietf.org/html/rfc to the RFC number and shows the URL in a footnote.

pandoc markdown quirks

If you have multiple inline footnotes in the same paragraph but on different lines of the markdown, all lines except the last must end with a trailing space.

man page subsections are h4 #### to keep from showing up in the contents. Pandoc 2.8 should have a way to suppress h3 from contents.

Table rows need to be on one line for proper wrapping (newlines are preserved in table cells).

Tables: the relative widths of the headers is reflected in the final output.

Table header template:

| Macro           | Description                                            |
|-----------------|--------------------------------------------------------|

<a name> doesn't work. Use header {#tags}.

Fenced code with a standard language name can sometimes cause LaTeX to puke.

```c                   Don't do this

``` {.c}               Do this
``` {.c .numberLines}  Or this

Indexing done with latex \index{foo} markers. They don't show up in HTML output.

LaTex indexing examples:

(Escape underscores with \_!)

\index{foo} plain element
\index{foo\_bar} element with underscore
\index{foo()@\texttt{foo()}} render foo() in monospace in index
\index{O\_NONBLOCK@\texttt{O\_NONBLOCK}} mono with underscores
\index{foo!bar} subindex bar in foo
\index{bind()@\texttt{bind()}!implicit} subindex with mono

More LaTeX indexing examples here.

Index entries should be at the main level and not in headers or bold or italicized text (or they'll appear as seperate entries in the index).

Put a \newpage before each manpage to force a page break.

When editing bgnet_amazon.md, use \newpage to force widows onto the next page.

Footnotes after links on sequential lines need a blank space at the end of the line to work properly...?

[Hey](url)^[footnote],   <-- Need a blank space at the end of this line
[Again](url2)^[footnote2].