markman

markdown man page converter
git clone git://edryd.org/markman
Log | Files | Refs | README | LICENSE

README.md (2549B)

      1 # markman \- markdown to man page converter
      2 
      3 Simple ad hoc generation of Unix man pages from markdown files.
      4 It includes customizations and ability to supply additional information or formatting needed for man
      5 pages not found in traditional markdown.
      6 For example, you can add a synopsis section from a command's help message, convert the title
      7 header into the name section, or add a description header before the first paragraph.
      8 This allows any markdown document to become a manual, including this very README.
      9 
     10 ## Options
     11 
     12 #### -c
     13 
     14 Disable auto capitalization of titles and section headers.
     15 
     16 #### -C
     17 
     18 Enable auto capitalization of titles and section headers (default).
     19 
     20 #### -t TITLE
     21 
     22 Title displayed at top of man page, usually name of program. Defaults to file name or `stdin`.
     23 
     24 #### -d DATE
     25 
     26 Date man page was updated, displayed at bottom center. Defaults to current date in YYYY-MM-DD
     27 format.
     28 
     29 #### -V VERSION
     30 
     31 Version number of program being documented, displayed at bottom left.
     32 
     33 #### -m MIDDLE
     34 
     35 Text displayed at top middle of manual. Defaults to name of manual section.
     36 
     37 #### -n
     38 
     39 Convert the first header into a name section at the top of the man page.
     40 
     41 #### -s SYNOPSIS
     42 
     43 Text to be inserted as a synopsis section at the top of the man page, under name section.
     44 
     45 #### -D
     46 
     47 Add description header to the top of the man page, under name or synopsis sections if supplied.
     48 This allows most standard markdown documents to conform to the man page convention where the first
     49 paragraphs are in the description section.
     50 
     51 #### -SECTION
     52 
     53 Set man page section number, be can number from 1 to 8:
     54 
     55 * **1**: General commands
     56 * **2**: System calls
     57 * **3**: Library functions (eg C standard library)
     58 * **4**: Special files and drivers (eg /dev)
     59 * **5**: File formats and conventions
     60 * **6**: Games and screensavers
     61 * **7**: Miscellaneous
     62 * **8**: System admin commands and daemons
     63 
     64 #### -h
     65 
     66 Print help and exit.
     67 
     68 #### -v
     69 
     70 Print version info and exit.
     71 
     72 ## Usage
     73 
     74 Convert this README into a man page:
     75 
     76 ```
     77 markman -Dn -s "`markman -h 2>&1 | cut -d' ' -f2-`" -t $(EXE) -d "`date '+%B %Y'`" -V $(VERSION) README.md > $(EXE).1
     78 ```
     79 
     80 ## See Also
     81 
     82 See project at <https://edryd.org/projects/markman>
     83 
     84 View source code at <https://git.edryd.org/markman>
     85 
     86 Projects which use markman to generate their man pages:
     87 
     88 * markman
     89 * [eevo](https://eevo.pub)
     90 * [gst](https://edryd.org/projects/gst)
     91 
     92 [Pandoc](https://pandoc.org/) is also a great alternative for a more general purpose markdown
     93 converter.
     94 
     95 ## Author
     96 
     97 Edryd van Bruggen <ed@edryd.org>
     98 
     99 ## License
    100 
    101 zlib License