AMN(1)                      General Commands Manual                     AMN(1)



NAME
       amn - man maker

SYNOPSIS
       amn [-hHV137] [-D key=str] [file|stdin]

TL;DR
       make man:

            ~$ amn <<- 'EEE'
            @name hw - hello, world
            @synopsis hw [-hH] file...
            @description disp `hello`, `_world`
            EEE

            ~$ amn <<- 'EEE' |man /dev/stdin
            title=xyz section=3
            @name hw - hello, world
            @_syno
            #include "hw.h"
            int hw(int ac, char** av);
            @_desc use c-func parser in @synopsis if section is `_2` or `3`
            EEE

       read from stdin if ag1 file isnt exist
            ~$ anm src.txt
            ~$ anm <src.txt
            ~$ cat src.txt | anm | man /dev/stdin
            ~$ cat src.txt | anm -D title=abc


OPTIONS
       -h, -H, -V
              print usage, version info

       -1, -3, -7
              output sample command

       -D key=str
              overwrite default settings

       opt -D key are the below. val str \[\abfnrtv], \ooo, \xhh is converted.
       null-char \0 causes undefined results.
         mk   : tag marker. used for charesc too. dfl=@
         hlop : bold/underline highlight block open. dfl=` (back quote)
         hlcl : close. dfl=\047
         ulstr: underline flag. dfl=_. `_str` makes underline, str
         tagop: tag open. @(pre) etc. dfl=(
         tagcl: close. dfl=)
         lbdlm: works only in @(list), -a: info..., etc. dfl=:
         brstr: break marker. dfl=--. --(\n) works as <br>.
         repnl: replace nl. dfl=  (del). latin-type lang may need \s==\040
         zwsp : insert zwsp to all chars if set 1. dfl=0
                man misses locale if read file from local.
                  ~$ man abc.1       #>> valil, locale=ja_JP etc
                  ~$ cp /usr/share/man/ja/man1/abc.1.gz ./
                  ~$ man ./abc.1.gz       #>> broken format locale=C ?
                man preprocesser causes this problem. abc.1.gz is valid.
                zwsp temporary improves broken format at editing/making doc.
                dont use zwsp to release doc. (h|e|l|l|o ...redundant)
                you can resolve this probrem using groff delective .mso.
                  ~$ (echo .mso ja.tmac; cat ./abc.1) | man -l -
                -l - means read locale + stdin(-). see man(1), groff(7)

       next keys change manpage settings
         title   : manpage title. dfl=no_title
         section : man section. dfl=1
         footer  : dfl isnt set
         footer_l: dfl isnt set
         header  : dfl isnt set


DESCRIPTION
       amn converts markup text to manpages. basic rule is close to html.
         - tab, newline, emptylines are ignored
         - spaces are merged to 1 char
       a typical example is the below:
       ---
         title=hello section=1
         header=GNU  repnl=\040
         @name hw
         @_brief hello, world
         @_syno hw [-h|-H] file ...
         @options option list is --
           @(list)
           -h: escape quote, colon.. @`help@` @: etc
           `-v`: version
           @()
         @_see ls(1), `pwd(1)` `_puts(3)`
       ---

       amn accepts the following syntax:


       key=str
              from BOF to 1st @XXX is defination block.
              - grep only XX=YY str. ignore others
              - dont quote. mk='@' is bad. title=a\101c is valid.
              - str is sapareted with sp/tab. use \040 if needs space \s.
              - str is converted with printf(str).
              - option -Dkey=str overwrites defination block settings.


       @XXX   header, @name etc. make uppercase. must be BOL. XXX is converted
              with printf(XXX). @conforming\040to etc.

       @_XXX  same as @XXX, but some words are reserved to alias/macros.
                @_syno : @SYNOPSIS
                @_opt  : @OPTIONS
                @_desc : @DESCRIPTION
                @_eg   : @EXSAMPLE
                @_ver  : @VERSION
                @_see  : @SEE_ALSO
                @_brief: add description to @NAME


       @(pre)...@()
              <pre>..</pre>. highlighting, charesc, @(raw) works

       @(code)..@()
              similar to @(pre) but any syntax/tag doesnt work

       @(list)..@()
              list. splits label and info with colon ':'. if use colon char in
              infostr, use '@:' . nl, --(\n) cant use in label.
              eg) it@`s a `la``_bel`: m`sg` @: --(\n)@(raw).RS@()  ..valid


       @(list_o)..@()
              list for command options. highlight label automatically
              eg) -n, --num[=n]: set num >>> -n, --num[=n] set num

       @(raw)...@()
              pass rawstr to groff. no needs to set \n at the block end.
              eg) abc@(raw).SH new_section@()123

       @() + \n
              works as block end if exists in the EOL. if block isnt  open  or
              not EOL, ignored/skipped.
              eg) abc@()123 >>> abc123, do nothing

       `str`  bold str. keep inner sp/tabs. use @`, @@ to write `, @

       `_str` underline str. 1 char `_` works as bold

       ``str``
              backquote x2, no highlighting. you dont need esc quote.
              eg) `` `abc` esc @` @@ works too`` >> `abc` esc ` @ works too

       @`     back quote. you can also use groff esc @(raw) \(ga @()

       @@     atmark. you can also use groff @(raw) @ @()

       @:     colon. maybe uses only for @(list) or @(list_o). @(raw) : @()

       --(\n) 2-hyphen  +  nl.  <br>. --(\s)(\n) doesnt work. gnu_man seems to
              merge blanklines at output, so you cant use multi-blanklines.


       if @(pre,code,list,list_o) end with @(...)\n, deletes \n char.
       if they end with @(...)--\n, add a empty line before the block.
       if @(pre,code) block end with @(...)@\n, remove  the  leading  tabs  as
       shell heredoc  `<<-`  syntax.
       if  they end with @(...)--@\n, add a empty lines and remove the leading
       tabs.
       if @() end with @()--\n or @()--@\n, add a empty line after block.
       if @() end with @()@\n, work the same as @()\n. (ignores end @).
       summary example is the below:

       aaa              aaa          |  aaa              aaa
       @(code)          \t   \s 000  |  @(code)@            000
       \t   \s 000  >>  \s \t   111  |          000  >>          111
       \s \t   111      zzz          |          111
       @()\n                         |  @()--            zzz
       zzz                           |  zzz
       - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - -
       aaa              aaa          |  aaa              aaa
       @(code)--                     |  @(code)--@
               000  >>          000  |          000  >>     000
               111              111  |          111              111
       @()@             zzz          |  @()--@
       zzz                           |  zzz              zzz

       the @(list_o) label and @SYNOPSIS block are highlighted  automatically.
       @(list_o) label is assumed to be command options -a, --all[=str] etc.
       @SYNOPSIS parser is changed by -Dsection=num setting

       section 1
              detect  command  format,  "cmd  [-a ag] file" etc. use --(\n) to
              split long command description:
                  eg) cmd [-a ag] --(\n)(\t) [-b] file

       section 2/3
              detect C-func decreations "int myf(int num);" etc.  use   simple
              (\n) to split long string. (allow --(\n) too)
              this block works as @(pre) block with C-func highlighting.

       the parsers are heuristic but work for the most part.

EXSAMPLE
       --
       @name hw - hello, world
       @_desc disp --
         @(raw)...@()
         `messages` ...

       --
       mk=#_@ brstr=???
       #_@name hw - hello, world
       #_@_desc disp ???
         #_@(raw)...#_@()
         `messages` ...



CONFORMING_TO
       posix-sh, POSIX.1-2001+

NOTES
       if you needs to html converter, use mandoc.
        ~$ cat amn.1 | mandoc -Thtml > amn.1.html
        ~$ cat amn.1 | mandoc -Tpdf > amn.1.pdf

       gnu_man has self html parser (man -H) but not so good
        ~$ cat amn.1 |man -Hcat /dev/stdin > amn.1.html

       if you needs plaintext, use man or mandoc.
        ~$ mandoc -Tutf8 <amn.1 | sed -e "s/.`printf '\\b'`//g"> amn.1.txt
        ~$ amn -7|amn -Dzwsp=1 |
                 man -Tutf8 /dev/stdin|sed -e "s/.`printf '\\b'`//g"> amn.7.txt
        (-Dzwsp=1 + man makes terminal 80x24 suitable text in multibyte locale)


COPYRIGHT
       Copyright (C) 2021 Momi-g
       License GPLv3+ <https://gnu.org/licenses/gpl.html>.

VERSION
       2021-12-02 v1.1.1

SEE_ALSO
       man-pages(7), groff_man(7), groff(7), mandoc(1)
       https://wiki.archlinux.org/title/Man_page

       ...recommend to read man-pages(7), arch_wiki



                                                                        AMN(1)
