emo/thin-provisioning-tools
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[manpages] Update txt2man to 1.7.1

Browse Source 
Signed-off-by: Kay Lin <i@v2bv.net>
This commit is contained in:
Kay Lin 2021-01-22 06:03:38 -08:00 committed by Ming-Hung Tsai
parent 2d201c5483
commit 6f1a6a59dd
1 changed files with 107 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
bin/txt2man
View File

@ -1,5 +1,4 @@
#!/bin/sh #!/bin/sh
test "$HOME" = ~ || exec ksh $0 "$@" # try ksh if sh too old (not yet POSIX)
# Copyright (C) 2001, 2002, 2003 Marc Vertes # Copyright (C) 2001, 2002, 2003 Marc Vertes
@ -18,7 +17,7 @@ test "$HOME" = ~ || exec ksh $0 "$@" # try ksh if sh too old (not yet POSIX)
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
# 02111-1307, USA. # 02111-1307, USA.
# txt2man-1.5 # release 1.7.1
usage() usage()
{ {
@ -27,7 +26,7 @@ NAME
txt2man - convert flat ASCII text to man page format txt2man - convert flat ASCII text to man page format
SYNOPSIS SYNOPSIS
txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect] txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
[-v vol] [-I txt] [-B txt] [ifile] [-v vol] [-I txt] [-B txt] [-d date] [ifile]
DESCRIPTION DESCRIPTION
txt2man converts the input text into nroff/troff standard man(7) txt2man converts the input text into nroff/troff standard man(7)
macros used to format Unix manual pages. Nice pages can be generated macros used to format Unix manual pages. Nice pages can be generated
@ -45,26 +44,32 @@ DESCRIPTION
Here is how text patterns are recognized and processed: Here is how text patterns are recognized and processed:
Sections These headers are defined by a line in upper case, starting Sections These headers are defined by a line in upper case, starting
column 1. If there is one or more leading spaces, a column 1. If there is one or more leading spaces, a
sub-section will be generated instead. sub-section will be generated instead. Optionally, the
Section name can be preceded by a blank line. This is useful
for a better visualization of the source text to be used to
generate the manpage.
Paragraphs They must be separated by a blank line, and left aligned. Paragraphs They must be separated by a blank line, and left aligned.
Alternatively two blank spaces can be used to produce the
same result. This option will provide a better visualization
of the source text to be used to generate the manpage.
Tag list The item definition is separated from the item description Tag list The item definition is separated from the item description
by at least 2 blank spaces, even before a new line, if by at least 2 blank spaces, even before a new line, if
definition is too long. Definition will be emphasized definition is too long. Definition will be emphasized
by default. by default.
Bullet list Bullet list
Bullet list items are defined by the first word being "-" Bullet list items are defined by the first word being "-"
or "*" or "o". or "*" or "o".
Enumerated list Enumerated list
The first word must be a number followed by a dot. The first word must be a number followed by a dot.
Literal display blocks Literal display blocks
This paragraph type is used to display unmodified text, This paragraph type is used to display unmodified text,
for example source code. It must be separated by a blank for example source code. It must be separated by a blank
line, and be indented. It is primarily used to format line and be indented by a TAB. It is primarily used to format
unmodified source code. It will be printed using fixed font unmodified source code. It will be printed using fixed font
whenever possible (troff). whenever possible (troff).
Cross references Cross references
A cross reference (another man page) is defined by a word A cross reference (another man page) is defined by a word
followed by a number in parenthesis. followed by a number in parenthesis.
Special sections: Special sections:
NAME The function or command name and short description are set in NAME The function or command name and short description are set in
@ -72,37 +77,45 @@ DESCRIPTION
SYNOPSIS This section receives a special treatment to identify command SYNOPSIS This section receives a special treatment to identify command
name, flags and arguments, and propagate corresponding name, flags and arguments, and propagate corresponding
attributes later in the text. If a C like function is recognized attributes later in the text. If a C like function is recognized
(word immediately followed by an open parenthesis), txt2man will (word immediately followed by an open parenthesis), txt2man will
print function name in bold font, types in normal font, and print function name in bold font, types in normal font, and
variables in italic font. The whole section will be printed using variables in italic font. The whole section will be printed using
a fixed font family (courier) whenever possible (troff). a fixed font family (courier) whenever possible (troff).
It is a good practice to embed documentation into source code, by using It is a good practice to embed documentation into source code, by using
comments or constant text variables. txt2man allows to do that, keeping comments or constant text variables. txt2man allows one to do that, keeping
the document source readable, usable even without further formatting the document source readable, usable even without further formatting
(i.e. for online help) and easy to write. The result is high quality (i.e. for online help) and easy to write. The result is high quality
and standard complying document. and standard complying document.
OPTIONS OPTIONS
-h The option -h displays help. -h The option -h displays help.
-d date Set date in header. Defaults to current date.
-P pname Set pname as project name in header. Default to uname -s. -P pname Set pname as project name in header. Default to uname -s.
-p Probe title, section name and volume. -p Probe title, section name and volume.
-t mytitle Set mytitle as title of generated man page. -t mytitle Set mytitle as title of generated man page.
-r rel Set rel as project name and release. -r rel Set rel as project name and release.
-s sect Set sect as section in heading, ususally a value from 1 to 8. -s sect Set sect as section in heading, usually a value from 1 to 8.
-v vol Set vol as volume name, i.e. "Unix user 's manual". -v vol Set vol as volume name, i.e. "Unix user 's manual".
-I txt Italicize txt in output. Can be specified more than once. -I txt Italicize txt in output. Can be specified more than once.
-B txt Emphasize (bold) txt in output. Can be specified more than once. -B txt Emphasize (bold) txt in output. Can be specified more than once.
-T Text result previewing using PAGER, usually more(1). -T Text result previewing using PAGER, usually more(1).
-X X11 result previewing using gxditview(1). -X X11 result previewing using gxditview(1).
ENVIRONMENT ENVIRONMENT
PAGER name of paging command, usually more(1), or less(1). If not set PAGER name of paging command, usually more(1), or less(1). If not set
falls back to more(1). falls back to more(1).
EXAMPLE SOURCE_DATE_EPOCH Unix timestamp that is used for date in header instead
of current date.
EXAMPLES
Try this command to format this text itself: Try this command to format this text itself:
$ txt2man -h 2>&1 | txt2man -T $ txt2man -h 2>&1 | txt2man -T
The following command will generate a manpage level 1 to foo-1.1.0 program,
from foo.txt file, used as source code to previously mentioned manpage:
$ txt2man -d "15 May 2016" -t foo -r foo-1.1.0 -s 1 -v "show stars on screen" foo.txt > foo.1
HINTS HINTS
To obtain an overall good formating of output document, keep paragraphs To obtain an overall good formatting of output document, keep paragraphs
indented correctly. If you have unwanted bold sections, search for indented correctly. If you have unwanted bold sections, search for
multiple spaces between words, which are used to identify a tag list multiple spaces between words, which are used to identify a tag list
(term followed by a description). Choose also carefully the name of (term followed by a description). Choose also carefully the name of
@ -127,47 +140,65 @@ doprobe=
itxt= itxt=
btxt= btxt=
post=cat post=cat
while getopts :hpTXr:s:t:v:P:I:B: opt while getopts :d:hpTXr:s:t:v:P:I:B: opt
do do
case $opt in case $opt in
r) rel=$OPTARG;; (d) date=$OPTARG;;
t) title=$OPTARG;; (r) rel=$OPTARG;;
s) section=$OPTARG;; (t) title=$OPTARG;;
v) volume=$OPTARG;; (s) section=$OPTARG;;
P) sys=$OPTARG;; (v) volume=$OPTARG;;
p) doprobe=1;; (P) sys=$OPTARG;;
I) itxt="$OPTARG§$itxt";; (p) doprobe=1;;
B) btxt=$OPTARG;; (I) itxt="$OPTARG§$itxt";;
T) post="groff -mandoc -Tlatin1 | ${PAGER:-more}";; (B) btxt="$OPTARG§$btxt";;
X) post="groff -mandoc -X";; (T) post="groff -mandoc -Tlatin1 | ${PAGER:-more}";;
*) usage; exit;; (X) post="groff -mandoc -TX100-12 -rS12";;
(*) usage; exit;;
esac esac
done done
shift $(($OPTIND - 1)) shift $(($OPTIND - 1))
# Compatibility wrapper for BSD/GNU date, for parsing dates
if date -j >/dev/null 2>&1; then
pdate() { date -u -j -f '@%s' "$@"; }
else
pdate() { date -u -d "$@"; }
fi
if [ -n "$SOURCE_DATE_EPOCH" ]; then
date=$(LC_ALL=C pdate "@$SOURCE_DATE_EPOCH" +'%d %B %Y')
fi
date=${date:-$(LC_ALL=C date -u +'%d %B %Y')}
if test "$doprobe" if test "$doprobe"
then then
title=${1##*/}; title=${title%.txt} title=${1##*/}; title=${title%.txt}
section="8" if grep -q '#include ' $1
volume="System Manager's Manual" then
section=${section:-3}
volume=${volume:-"$sys Programmer's Manual"}
else
section=${section:-1}
volume=${volume:-"$sys Reference Manual"}
fi
# get release from path # get release from path
#rel=$(pwd | sed 's:/.*[^0-9]/::g; s:/.*::g') rel=${rel:-"$(pwd | sed 's:/.*[^0-9]/::g; s:/.*::g')"}
rel="Device Mapper Tools"
fi fi
head=".\\\" Text automatically generated by txt2man head="\" Text automatically generated by txt2man
.TH $title $section \"$rel\" \"$volume\"" .TH $title $section \"$date\" \"$rel\" \"$volume\""
# All tabs converted to spaces # All tabs converted to spaces
expand $* | expand $* |
# gawk is needed because use of non standard regexp # gawk is needed because use of non standard regexp
gawk --re-interval -v head="$head" -v itxt="$itxt" -v btxt="$btxt" ' gawk --re-interval -v head="$head" -v itxt="$itxt" -v btxt="$btxt" '
BEGIN { BEGIN {
print head print ".\\" head
avar[1] = btxt; avar[2] = itxt avar[1] = btxt; avar[2] = itxt
for (k in avar) { for (k in avar) {
mark = (k == 1) ? "\\fB" : "\\fI" mark = (k == 1) ? "\\fB" : "\\fI"
split(avar[k], tt, "§") split(avar[k], tt, "§")
for (i in tt) for (i in tt)
if (tt[i] != "") if (tt[i] != "")
subwords["\\<" tt[i] "\\>"] = mark tt[i] "\\fP" subwords["\\<" tt[i] "\\>"] = mark tt[i] "\\fP"
@ -179,11 +210,11 @@ BEGIN {
} }
{ {
# to avoid some side effects in regexp # to avoid some side effects in regexp
sub(/\.\.\./, "\\.\\.\\.") gsub(/\.\.\./, "\\.\\.\\.")
# remove spaces in empty lines # remove spaces in empty lines
sub(/^ +$/,"") sub(/^ +$/,"")
} }
/^[[:upper:][:space:]]+$/ { /^[:space:]*[[:upper:][:digit:]]+[[:upper:][:space:][:digit:][:punct:]]+$/ {
# Section header # Section header
if ((in_bd + 0) == 1) { if ((in_bd + 0) == 1) {
in_bd = 0 in_bd = 0
@ -199,8 +230,10 @@ BEGIN {
print ".SS" $0 print ".SS" $0
sub(/^ +/, "") sub(/^ +/, "")
section = $0 section = $0
if (section == "SYNOPSIS") if (section == "SYNOPSIS") {
print ".nf\n.fam C" print ".nf\n.fam C"
in_bd = 1
}
ls = 0 # line start index ls = 0 # line start index
pls = 0 # previous line start index pls = 0 # previous line start index
pnzls = 0 # previous non zero line start index pnzls = 0 # previous non zero line start index
@ -216,7 +249,7 @@ BEGIN {
pnzls = ls pnzls = ls
match($0, /[^ ]/) match($0, /[^ ]/)
ls = RSTART ls = RSTART
if (pls == 0 && pnzls > 0 && ls > pnzls && $1 !~ /^[0-9\-\*\o]\.*$/) { if (in_bd == 0 && pls == 0 && pnzls > 0 && ls > pnzls && $1 !~ /^[\-\*o]$|^[0-9]+\.$/) {
# example display block # example display block
if (prevblankline == 1) { if (prevblankline == 1) {
print ".PP" print ".PP"
@ -230,8 +263,10 @@ BEGIN {
ind[0] = ls ind[0] = ls
} }
(in_bd + 0) == 1 { (in_bd + 0) == 1 {
# In example display block # In block display
if (ls != 0 && ls < eoff) { if (section == "SYNOPSIS")
;
else if (ls != 0 && ls < eoff) {
# End of litteral display block # End of litteral display block
in_bd = 0 in_bd = 0
print ".fam T\n.fi" print ".fam T\n.fi"
@ -244,11 +279,12 @@ section == "NAME" {
section == "SYNOPSIS" { section == "SYNOPSIS" {
# Identify arguments of fcts and cmds # Identify arguments of fcts and cmds
if (type["SYNOPSIS"] == "") { if (type["SYNOPSIS"] == "") {
if (index($0, "(") == 0 && index($0, ")") == 0 && if ($0 ~ /\(/)
index($0, "#include") == 0)
type["SYNOPSIS"] = "cmd"
else
type["SYNOPSIS"] = "fct" type["SYNOPSIS"] = "fct"
else if ($1 == "struct" || $2 == "struct")
type["SYNOPSIS"] = "struct"
else if ($1 && $1 !~ /^#|typedef|struct|union|enum/)
type["SYNOPSIS"] = "cmd"
} }
if (type["SYNOPSIS"] == "cmd") { if (type["SYNOPSIS"] == "cmd") {
# Line is a command line # Line is a command line
@ -263,19 +299,19 @@ section == "SYNOPSIS" {
if (a ~ /^[^\-]/) if (a ~ /^[^\-]/)
subwords["\\<" a "\\>"] = "\\fI" a "\\fP" subwords["\\<" a "\\>"] = "\\fI" a "\\fP"
} }
} else { } else if (type["SYNOPSIS"] == "fct") {
# Line is a C function definition # Line is a C function definition
if ($1 == "typedef") if ($1 == "typedef") {
subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP" if ($0 !~ /\(\*/)
else if ($1 == "#define") subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP"
} else if ($1 == "#define")
subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP" subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP"
for (i = 1; i <= NF; i++) { for (i = 1; i <= NF; i++) {
if ($i ~ /[\,\)]/) { if ($i ~ /[,\)];*$/) {
a = $i a = $i
sub(/.*\(/, "", a) sub(/.*\(/, "", a)
gsub(/\W/, "", a) gsub(/\W/, "", a)
if (a !~ /^void$/) subwords["\\<" a "\\>"] = "\\fI" a "\\fP"
subwords["\\<" a "\\>"] = "\\fI" a "\\fP"
} }
} }
} }
@ -298,13 +334,19 @@ section == "SYNOPSIS" {
} }
} }
# word attributes # word attributes
for (i in subwords) n = asorti(subwords, indices)
gsub(i, subwords[i]) for (i = 1; i <= n; i++)
gsub(indices[i], subwords[indices[i]])
# shell options # shell options
gsub(/\B\-+\w+(\-\w+)*/, "\\fB&\\fP") gsub(/\B\-+\w+(\-\w+)*/, "\\fB&\\fP")
# unprotect dots inside words # unprotect dots inside words
gsub(/_dOt_/, ".") gsub(/_dOt_/, ".")
if (section == "SYNOPSIS") {
sub(/^ /, "")
print
next
}
if (match($0, /[^ ] +/) > 0) { if (match($0, /[^ ] +/) > 0) {
# tag list item # tag list item
adjust_indent() adjust_indent()
@ -347,6 +389,8 @@ section == "SYNOPSIS" {
} }
if (section != "SYNOPSIS" || $0 ~ /^ {1,4}/) if (section != "SYNOPSIS" || $0 ~ /^ {1,4}/)
sub(/ */,"") sub(/ */,"")
# Protect lines starting by simple quotes
sub(/^'\''/, "\\(cq")
print print
} }