amn - man maker
amn [
-hHV137] [
-D key=
str]
[
file|
stdin]
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
- -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
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 -D key=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.
--
@name hw - hello, world
@_desc disp --
@(raw)...@()
`messages` ...
--
mk=#_@ brstr=???
#_@name hw - hello, world
#_@_desc disp ???
#_@(raw)...#_@()
`messages` ...
posix-sh, POSIX.1-2001+
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 (C) 2021 Momi-g
License GPLv3+ <https://gnu.org/licenses/gpl.html>.
2021-12-02 v1.1.1
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