[manpages] Update txt2man to 1.7.1
Signed-off-by: Kay Lin <i@v2bv.net>
This commit is contained in:
Kay Lin
Ming-Hung Tsai
parent
2d201c5483
commit
6f1a6a59dd
170
bin/txt2man
170
bin/txt2man
@ -1,5 +1,4 @@
|
||||
#!/bin/sh
|
||||
test "$HOME" = ~ || exec ksh $0 "$@" # try ksh if sh too old (not yet POSIX)
|
||||
|
||||
# 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
|
||||
# 02111-1307, USA.
|
||||
|
||||
# txt2man-1.5
|
||||
# release 1.7.1
|
||||
|
||||
usage()
|
||||
{
|
||||
@ -27,7 +26,7 @@ NAME
|
||||
txt2man - convert flat ASCII text to man page format
|
||||
SYNOPSIS
|
||||
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
|
||||
txt2man converts the input text into nroff/troff standard man(7)
|
||||
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:
|
||||
Sections These headers are defined by a line in upper case, starting
|
||||
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.
|
||||
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
|
||||
by at least 2 blank spaces, even before a new line, if
|
||||
definition is too long. Definition will be emphasized
|
||||
by default.
|
||||
Bullet list
|
||||
Bullet list items are defined by the first word being "-"
|
||||
or "*" or "o".
|
||||
or "*" or "o".
|
||||
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
|
||||
This paragraph type is used to display unmodified text,
|
||||
for example source code. It must be separated by a blank
|
||||
line, and be indented. It is primarily used to format
|
||||
unmodified source code. It will be printed using fixed font
|
||||
whenever possible (troff).
|
||||
This paragraph type is used to display unmodified text,
|
||||
for example source code. It must be separated by a blank
|
||||
line and be indented by a TAB. It is primarily used to format
|
||||
unmodified source code. It will be printed using fixed font
|
||||
whenever possible (troff).
|
||||
Cross references
|
||||
A cross reference (another man page) is defined by a word
|
||||
followed by a number in parenthesis.
|
||||
A cross reference (another man page) is defined by a word
|
||||
followed by a number in parenthesis.
|
||||
|
||||
Special sections:
|
||||
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
|
||||
name, flags and arguments, and propagate corresponding
|
||||
attributes later in the text. If a C like function is recognized
|
||||
(word immediately followed by an open parenthesis), txt2man will
|
||||
print function name in bold font, types in normal font, and
|
||||
variables in italic font. The whole section will be printed using
|
||||
a fixed font family (courier) whenever possible (troff).
|
||||
(word immediately followed by an open parenthesis), txt2man will
|
||||
print function name in bold font, types in normal font, and
|
||||
variables in italic font. The whole section will be printed using
|
||||
a fixed font family (courier) whenever possible (troff).
|
||||
|
||||
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
|
||||
(i.e. for online help) and easy to write. The result is high quality
|
||||
and standard complying document.
|
||||
OPTIONS
|
||||
-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 Probe title, section name and volume.
|
||||
-t mytitle Set mytitle as title of generated man page.
|
||||
-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".
|
||||
-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.
|
||||
-T Text result previewing using PAGER, usually more(1).
|
||||
-X X11 result previewing using gxditview(1).
|
||||
ENVIRONMENT
|
||||
PAGER name of paging command, usually more(1), or less(1). If not set
|
||||
falls back to more(1).
|
||||
EXAMPLE
|
||||
PAGER name of paging command, usually more(1), or less(1). If not set
|
||||
falls back to more(1).
|
||||
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:
|
||||
|
||||
$ 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
|
||||
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
|
||||
multiple spaces between words, which are used to identify a tag list
|
||||
(term followed by a description). Choose also carefully the name of
|
||||
@ -127,47 +140,65 @@ doprobe=
|
||||
itxt=
|
||||
btxt=
|
||||
post=cat
|
||||
while getopts :hpTXr:s:t:v:P:I:B: opt
|
||||
while getopts :d:hpTXr:s:t:v:P:I:B: opt
|
||||
do
|
||||
case $opt in
|
||||
r) rel=$OPTARG;;
|
||||
t) title=$OPTARG;;
|
||||
s) section=$OPTARG;;
|
||||
v) volume=$OPTARG;;
|
||||
P) sys=$OPTARG;;
|
||||
p) doprobe=1;;
|
||||
I) itxt="$OPTARG§$itxt";;
|
||||
B) btxt=$OPTARG;;
|
||||
T) post="groff -mandoc -Tlatin1 | ${PAGER:-more}";;
|
||||
X) post="groff -mandoc -X";;
|
||||
*) usage; exit;;
|
||||
(d) date=$OPTARG;;
|
||||
(r) rel=$OPTARG;;
|
||||
(t) title=$OPTARG;;
|
||||
(s) section=$OPTARG;;
|
||||
(v) volume=$OPTARG;;
|
||||
(P) sys=$OPTARG;;
|
||||
(p) doprobe=1;;
|
||||
(I) itxt="$OPTARG§$itxt";;
|
||||
(B) btxt="$OPTARG§$btxt";;
|
||||
(T) post="groff -mandoc -Tlatin1 | ${PAGER:-more}";;
|
||||
(X) post="groff -mandoc -TX100-12 -rS12";;
|
||||
(*) usage; exit;;
|
||||
esac
|
||||
done
|
||||
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"
|
||||
then
|
||||
title=${1##*/}; title=${title%.txt}
|
||||
section="8"
|
||||
volume="System Manager's Manual"
|
||||
if grep -q '#include ' $1
|
||||
then
|
||||
section=${section:-3}
|
||||
volume=${volume:-"$sys Programmer's Manual"}
|
||||
else
|
||||
section=${section:-1}
|
||||
volume=${volume:-"$sys Reference Manual"}
|
||||
fi
|
||||
# get release from path
|
||||
#rel=$(pwd | sed 's:/.*[^0-9]/::g; s:/.*::g')
|
||||
rel="Device Mapper Tools"
|
||||
rel=${rel:-"$(pwd | sed 's:/.*[^0-9]/::g; s:/.*::g')"}
|
||||
fi
|
||||
|
||||
head=".\\\" Text automatically generated by txt2man
|
||||
.TH $title $section \"$rel\" \"$volume\""
|
||||
head="\" Text automatically generated by txt2man
|
||||
.TH $title $section \"$date\" \"$rel\" \"$volume\""
|
||||
|
||||
# All tabs converted to spaces
|
||||
expand $* |
|
||||
# gawk is needed because use of non standard regexp
|
||||
gawk --re-interval -v head="$head" -v itxt="$itxt" -v btxt="$btxt" '
|
||||
BEGIN {
|
||||
print head
|
||||
print ".\\" head
|
||||
avar[1] = btxt; avar[2] = itxt
|
||||
for (k in avar) {
|
||||
mark = (k == 1) ? "\\fB" : "\\fI"
|
||||
split(avar[k], tt, "§")
|
||||
split(avar[k], tt, "§")
|
||||
for (i in tt)
|
||||
if (tt[i] != "")
|
||||
subwords["\\<" tt[i] "\\>"] = mark tt[i] "\\fP"
|
||||
@ -179,11 +210,11 @@ BEGIN {
|
||||
}
|
||||
{
|
||||
# to avoid some side effects in regexp
|
||||
sub(/\.\.\./, "\\.\\.\\.")
|
||||
gsub(/\.\.\./, "\\.\\.\\.")
|
||||
# remove spaces in empty lines
|
||||
sub(/^ +$/,"")
|
||||
}
|
||||
/^[[:upper:][:space:]]+$/ {
|
||||
/^[:space:]*[[:upper:][:digit:]]+[[:upper:][:space:][:digit:][:punct:]]+$/ {
|
||||
# Section header
|
||||
if ((in_bd + 0) == 1) {
|
||||
in_bd = 0
|
||||
@ -199,8 +230,10 @@ BEGIN {
|
||||
print ".SS" $0
|
||||
sub(/^ +/, "")
|
||||
section = $0
|
||||
if (section == "SYNOPSIS")
|
||||
if (section == "SYNOPSIS") {
|
||||
print ".nf\n.fam C"
|
||||
in_bd = 1
|
||||
}
|
||||
ls = 0 # line start index
|
||||
pls = 0 # previous line start index
|
||||
pnzls = 0 # previous non zero line start index
|
||||
@ -216,7 +249,7 @@ BEGIN {
|
||||
pnzls = ls
|
||||
match($0, /[^ ]/)
|
||||
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
|
||||
if (prevblankline == 1) {
|
||||
print ".PP"
|
||||
@ -230,8 +263,10 @@ BEGIN {
|
||||
ind[0] = ls
|
||||
}
|
||||
(in_bd + 0) == 1 {
|
||||
# In example display block
|
||||
if (ls != 0 && ls < eoff) {
|
||||
# In block display
|
||||
if (section == "SYNOPSIS")
|
||||
;
|
||||
else if (ls != 0 && ls < eoff) {
|
||||
# End of litteral display block
|
||||
in_bd = 0
|
||||
print ".fam T\n.fi"
|
||||
@ -244,11 +279,12 @@ section == "NAME" {
|
||||
section == "SYNOPSIS" {
|
||||
# Identify arguments of fcts and cmds
|
||||
if (type["SYNOPSIS"] == "") {
|
||||
if (index($0, "(") == 0 && index($0, ")") == 0 &&
|
||||
index($0, "#include") == 0)
|
||||
type["SYNOPSIS"] = "cmd"
|
||||
else
|
||||
if ($0 ~ /\(/)
|
||||
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") {
|
||||
# Line is a command line
|
||||
@ -263,19 +299,19 @@ section == "SYNOPSIS" {
|
||||
if (a ~ /^[^\-]/)
|
||||
subwords["\\<" a "\\>"] = "\\fI" a "\\fP"
|
||||
}
|
||||
} else {
|
||||
} else if (type["SYNOPSIS"] == "fct") {
|
||||
# Line is a C function definition
|
||||
if ($1 == "typedef")
|
||||
subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP"
|
||||
else if ($1 == "#define")
|
||||
if ($1 == "typedef") {
|
||||
if ($0 !~ /\(\*/)
|
||||
subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP"
|
||||
} else if ($1 == "#define")
|
||||
subwords["\\<" $2 "\\>"] = "\\fI" $2 "\\fP"
|
||||
for (i = 1; i <= NF; i++) {
|
||||
if ($i ~ /[\,\)]/) {
|
||||
if ($i ~ /[,\)];*$/) {
|
||||
a = $i
|
||||
sub(/.*\(/, "", 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
|
||||
for (i in subwords)
|
||||
gsub(i, subwords[i])
|
||||
n = asorti(subwords, indices)
|
||||
for (i = 1; i <= n; i++)
|
||||
gsub(indices[i], subwords[indices[i]])
|
||||
# shell options
|
||||
gsub(/\B\-+\w+(\-\w+)*/, "\\fB&\\fP")
|
||||
# unprotect dots inside words
|
||||
gsub(/_dOt_/, ".")
|
||||
|
||||
if (section == "SYNOPSIS") {
|
||||
sub(/^ /, "")
|
||||
print
|
||||
next
|
||||
}
|
||||
if (match($0, /[^ ] +/) > 0) {
|
||||
# tag list item
|
||||
adjust_indent()
|
||||
@ -347,6 +389,8 @@ section == "SYNOPSIS" {
|
||||
}
|
||||
if (section != "SYNOPSIS" || $0 ~ /^ {1,4}/)
|
||||
sub(/ */,"")
|
||||
# Protect lines starting by simple quotes
|
||||
sub(/^'\''/, "\\(cq")
|
||||
print
|
||||
}
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user