I use org-mode format for building example files. It’s a very powerful and flexible but it takes some time to master it.
Style requirements for exampls
Variables
VAR_STRING="string" VAR_NUM=1234 VAR_PATH="/path/to/somewhere"
Structure
Package name | Author | | | Maintainers | | | Released | | | Source | | | Info | | Long discription ----- * Index List of commands included in package with short description * Receipts ** command *** command::options *** command::examples *** command::files *** command::see-also * References ** Books ** Links ** Wiki ** IRC
Example header with time-stamp
**** command-YmdHMS short description:
#!/usr/bin/env sh
# Point to what shell did you use.
# Body, less word more examples!cmd (1) link to other command used
$ - system user commands # - system root user commands
Export *org files to {pdf,html,tex,txt,whatever}
- Emacs Org-Mode http://orgmode.org/manual/Exporting.html
- Pandoc http://pandoc.org/demos.html
- Org to Reveal.js https://github.com/yjwen/org-reveal
- Org to nice HTML https://github.com/fniessen/org-html-themes