From 2039e354d9ce878a406c8a7797f05096528363cb Mon Sep 17 00:00:00 2001 From: Tim Kientzle Date: Mon, 13 Apr 2009 17:08:53 -0400 Subject: First real attempt to convert all mdoc manpages to Wiki syntax. Including the awk script I'm using and updates to the doc generator to produce the Wiki versions as part of the regular deployment. SVN-Revision: 974 --- doc/html/.ignore_me | 2 + doc/mdoc2wiki.awk | 423 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/update.sh | 74 +++++++-- doc/wiki/.ignore_me | 2 + 4 files changed, 487 insertions(+), 14 deletions(-) create mode 100644 doc/html/.ignore_me create mode 100755 doc/mdoc2wiki.awk create mode 100644 doc/wiki/.ignore_me (limited to 'doc') diff --git a/doc/html/.ignore_me b/doc/html/.ignore_me new file mode 100644 index 00000000..d285484d --- /dev/null +++ b/doc/html/.ignore_me @@ -0,0 +1,2 @@ +*** PLEASE DO NOT DELETE THIS FILE! *** +This file is used to track an otherwise empty directory in git. diff --git a/doc/mdoc2wiki.awk b/doc/mdoc2wiki.awk new file mode 100755 index 00000000..91ac1d77 --- /dev/null +++ b/doc/mdoc2wiki.awk @@ -0,0 +1,423 @@ +#!/usr/bin/awk +# +# Copyright (c) 2003 Peter Stuge +# +# Permission to use, copy, modify, and distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +# Dramatically overhauled by Tim Kientzle. This version almost +# handles library-style pages with Fn, Ft, etc commands. Still +# a lot of problems... + +BEGIN { + displaylines = 0 + listdepth = 0 + trailer = "" + out = "" + sep = "" + nextsep = " " + spaces = " " +} + +# Add a word with appropriate preceding whitespace +# Maintain a short queue of the expected upcoming word separators. +function add(str) { + out=out sep str + sep = nextsep + nextsep = " " +} + +# Add a word with no following whitespace +# Use for opening punctuation such as '(' +function addopen(str) { + add(str) + sep = "" +} + +# Add a word with no preceding whitespace +# Use for closing punctuation such as ')' or '.' +function addclose(str) { + sep = "" + add(str) +} + +# Add a word with no space before or after +# Use for separating punctuation such as '=' +function addpunct(str) { + sep = "" + add(str) + sep = "" +} + +# Emit the current line so far +function endline() { + addclose(trailer) + trailer = "" + if(length(out) > 0) { + print out + out="" + } + if(displaylines > 0) { + displaylines = displaylines - 1 + if (displaylines == 0) + dispend() + } + # First word on next line has no preceding whitespace + sep = "" +} + +function linecmd(cmd) { + endline() + add(cmd) + endline() +} + +function breakline() { + linecmd("
") +} + +# Start an indented display +function dispstart() { + linecmd("{{{") +} + +# End an indented display +function dispend() { + linecmd("}}}") +} + +# Collect rest of input line +function wtail() { + retval="" + while(w 0) { + sub("^[ \t]*", "", l) + if (match(l, "^\"")) { + l = substr(l, 2) + o = index(l, "\"") + if (o > 0) { + w = substr(l, 1, o-1) + l = substr(l, o+1) + dest[n++] = w + } else { + dest[n++] = l + l = "" + } + } else { + o = match(l, "[ \t]") + if (o > 0) { + w = substr(l, 1, o-1) + l = substr(l, o+1) + dest[n++] = w + } else { + dest[n++] = l + l = "" + } + } + } + return n-1 +} + +! /^\./ { + out = $0 + endline() + next +} + +/^\.\\"/ { next } + +{ + sub("^\\.","") + nwords=splitwords($0, words) + # TODO: Instead of iterating 'w' over the array, have a separate + # function that returns 'next word' and use that. This will allow + # proper handling of double-quoted arguments as well. + for(w=1;w<=nwords;w++) { + if(match(words[w],"^Li$")) { # Literal; rest of line is unformatted + dispstart() + displaylines = 1 + } else if(match(words[w],"^Dl$")) { # Display literal + dispstart() + displaylines = 1 + } else if(match(words[w],"^Bd$")) { # Begin display + if(match(words[w+1],"-literal")) { + dispstart() + displaylines=10000 + w=nwords + } + } else if(match(words[w],"^Ed$")) { # End display + displaylines = 0 + dispend() + } else if(match(words[w],"^Ns$")) { # Suppress space after next word + nextsep = "" + } else if(match(words[w],"^No$")) { # Normal text + add(words[++w]) + } else if(match(words[w],"^Dq$")) { # Quote + addopen("\"") + add(words[++w]) + while(w") + } else if(match(words[w],"^Dd$")) { + date=wtail() + next + } else if(match(words[w],"^Dt$")) { + id=wtail() + next + } else if(match(words[w],"^Ox$")) { + add("OpenBSD") + } else if(match(words[w],"^Fx$")) { + add("FreeBSD") + } else if(match(words[w],"^Nx$")) { + add("NetBSD") + } else if(match(words[w],"^St$")) { + if (match(words[w+1], "^-p1003.1$")) { + w++ + add("IEEE Std 1003.1 (``POSIX.1'')") + } else if(match(words[w+1], "^-p1003.1-96$")) { + w++ + add("ISO/IEC 9945-1:1996 (``POSIX.1'')") + } else if(match(words[w+1], "^-p1003.1-88$")) { + w++ + add("IEEE Std 1003.1-1988 (``POSIX.1'')") + } else if(match(words[w+1], "^-p1003.1-2001$")) { + w++ + add("IEEE Std 1003.1-2001 (``POSIX.1'')") + } else if(match(words[w+1], "^-susv2$")) { + w++ + add("Version 2 of the Single UNIX Specification (``SUSv2'')") + } + } else if(match(words[w],"^Ex$")) { + if (match(words[w+1], "^-std$")) { + w++ + add("The *" name "* utility exits 0 on success, and >0 if an error occurs.") + } + } else if(match(words[w],"^Os$")) { + add("#summary " id " manual page") + } else if(match(words[w],"^Sh$")) { + section=wtail() + linecmd("== " section " ==") + } else if(match(words[w],"^Xr$")) { + add("*" words[++w] "*(" words[++w] ")" words[++w]) + } else if(match(words[w],"^Nm$")) { + if(match(section,"SYNOPSIS")) + breakline() + if(w >= nwords) + n=name + else if (match(words[w+1], "^[A-Z][a-z]$")) + n=name + else if (match(words[w+1], "^[.,;:]$")) + n=name + else { + n=words[++w] + if(!length(name)) + name=n + } + if(!length(n)) + n=name + add("*" n "*") + } else if(match(words[w],"^Nd$")) { + add("- " wtail()) + } else if(match(words[w],"^Fl$")) { + add("*-" words[++w] "*") + } else if(match(words[w],"^Ar$")) { + addopen("_") + if(w==nwords) + add("file ..._") + else + add(words[++w] "_") + } else if(match(words[w],"^Cm$")) { + add("*" words[++w] "*") + } else if(match(words[w],"^Op$")) { + addopen("[") + option=1 + trailer="]" trailer + } else if(match(words[w],"^Pp$")) { + linecmd("") + } else if(match(words[w],"^An$")) { + endline() + } else if(match(words[w],"^Ss$")) { + add("===") + } else if(match(words[w],"^Ft$")) { + if (match(section, "SYNOPSIS")) { + breakline() + } + l = wtail() + gsub("\\*", "`*`", l) + + add("*" l "*") + if (match(section, "SYNOPSIS")) { + breakline() + } + } else if(match(words[w],"^Fn$")) { + ++w + F = "*" words[w] "*(" + Fsep = "" + while(w*") + } else if(match(words[w],"^Pa$")) { + addopen("_") + w++ + if(match(words[w],"^\\.")) + add("\\&") + add(words[w] "_") + } else if(match(words[w],"^Dv$")) { + linecmd() + } else if(match(words[w],"^Em|Ev$")) { + add(".IR") + } else if(match(words[w],"^Pq$")) { + addopen("(") + trailer=")" trailer + } else if(match(words[w],"^Aq$")) { + addopen(" <") + trailer=">" trailer + } else if(match(words[w],"^Brq$")) { + addopen("{") + trailer="}" trailer + } else if(match(words[w],"^S[xy]$")) { + add(".B " wtail()) + } else if(match(words[w],"^Tn$")) { + add("*" wtail() "*") + } else if(match(words[w],"^Ic$")) { + add("\\fB") + trailer="\\fP" trailer + } else if(match(words[w],"^Bl$")) { + ++listdepth + listnext[listdepth]="" + if(match(words[w+1],"-bullet")) + optlist[listdepth]=1 + else if(match(words[w+1],"-enum")) { + optlist[listdepth]=2 + enum=0 + addopen("
    ") + listclose[listdepth]="
" + } else if(match(words[w+1],"-tag")) { + optlist[listdepth]=3 + addopen("
") + listclose[listdepth]="
" + } else if(match(words[w+1],"-item")) { + optlist[listdepth]=4 + addopen("
    ") + listclose[listdepth]="
" + } else if(match(words[w+1],"-bullet")) { + optlist[listdepth]=1 + addopen("
    ") + listclose[listdepth]="
" + } + w=nwords + } else if(match(words[w],"^El$")) { + addclose(listnext[listdepth]) + addclose(listclose[listdepth]) + listclose[listdepth]="" + listdepth-- + } else if(match(words[w],"^It$")) { + addclose(listnext[listdepth]) + if(optlist[listdepth]==1) { + addpunct("
  • ") + listnext[listdepth] = "
    • " + } else if(optlist[listdepth]==2) { + addpunct("
  • ") + listnext[listdepth] = "
    • " + } else if(optlist[listdepth]==3) { + addpunct("
    ") + listnext[listdepth] = "
    " + if(match(words[w+1],"^Xo$")) { + # Suppress trailer + w++ + } else if(match(words[w+1],"^Pa$|^Ev$")) { + add(".B") + w++ + } else { + trailer = listnext[listdepth] "
    " trailer + listnext[listdepth] = "
    " + } + } else if(optlist[listdepth]==4) { + addpunct("
  • ") + listnext[listdepth] = "
    • " + } + } else if(match(words[w],"^Xo$")) { + # TODO: Figure out how to handle this + } else if(match(words[w],"^Xc$")) { + # TODO: Figure out how to handle this + if (optlist[listdepth] == 3) { + addclose(listnext[listdepth]) + addopen("
    ") + listnext[listdepth] = "
    " + } + } else if(match(words[w],"^[=]$")) { + addpunct(words[w]) + } else if(match(words[w],"^[\[{(]$")) { + addopen(words[w]) + } else if(match(words[w],"^[\\\])}.,;:]$")) { + addclose(words[w]) + } else { + add(words[w]) + } + } + if(match(out,"^\\.[^a-zA-Z]")) + sub("^\\.","",out) + endline() +} diff --git a/doc/update.sh b/doc/update.sh index 925e09b6..0ac8f813 100755 --- a/doc/update.sh +++ b/doc/update.sh @@ -5,24 +5,22 @@ # the mdoc man pages stored in each project. # -# Remove existing manpages from the doc tree -chmod -R +w man text -rm -f man/*.[135] -rm -f text/*.txt -rm -f pdf/*.pdf +if false; then # Build Makefile in 'man' directory cd man +rm -f *.[135] echo > Makefile echo "default: all" >>Makefile echo >>Makefile all="all:" for d in libarchive tar cpio; do for f in ../../$d/*.[135]; do + outname="`basename $f`" echo >> Makefile - echo `basename $f`: ../mdoc2man.awk $f >> Makefile - echo " awk -f ../mdoc2man.awk < $f > `basename $f`" >> Makefile - all="$all `basename $f`" + echo $outname: ../mdoc2man.awk $f >> Makefile + echo " awk -f ../mdoc2man.awk < $f > $outname" >> Makefile + all="$all $outname" done done echo $all >>Makefile @@ -30,16 +28,18 @@ cd .. # Rebuild Makefile in 'text' directory cd text +rm -f *.txt echo > Makefile echo "default: all" >>Makefile echo >>Makefile all="all:" for d in libarchive tar cpio; do for f in ../../$d/*.[135]; do + outname="`basename $f`.txt" echo >> Makefile - echo `basename $f`.txt: $f >> Makefile - echo " nroff -mdoc $f | col -b > `basename $f`.txt" >> Makefile - all="$all `basename $f`.txt" + echo $outname: $f >> Makefile + echo " nroff -mdoc $f | col -b > $outname" >> Makefile + all="$all $outname" done done echo $all >>Makefile @@ -47,16 +47,58 @@ cd .. # Rebuild Makefile in 'pdf' directory cd pdf +rm -f *.pdf echo > Makefile echo "default: all" >>Makefile echo >>Makefile all="all:" for d in libarchive tar cpio; do for f in ../../$d/*.[135]; do + outname="`basename $f`.pdf" echo >> Makefile - echo `basename $f`.pdf: $f >> Makefile - echo " groff -mdoc -T ps $f | ps2pdf - - > `basename $f`.pdf" >> Makefile - all="$all `basename $f`.pdf" + echo $outname: $f >> Makefile + echo " groff -mdoc -T ps $f | ps2pdf - - > $outname" >> Makefile + all="$all $outname" + done +done +echo $all >>Makefile +cd .. + +# Build Makefile in 'html' directory +cd html +rm -f *.html +echo > Makefile +echo "default: all" >>Makefile +echo >>Makefile +all="all:" +for d in libarchive tar cpio; do + for f in ../../$d/*.[135]; do + outname="`basename $f`.html" + echo >> Makefile + echo $outname: ../mdoc2man.awk $f >> Makefile + echo " groff -mdoc -T html $f > $outname" >> Makefile + all="$all $outname" + done +done +echo $all >>Makefile +cd .. + +fi + +# Build Makefile in 'wiki' directory +cd wiki +rm -f *.wiki +echo > Makefile +echo "default: all" >>Makefile +echo >>Makefile +all="all:" +for d in libarchive tar cpio; do + for f in ../../$d/*.[135]; do + outname="`basename $f | awk '{ac=split($0,a,"[_.-]");o="ManPage";for(w=0;w<=ac;++w){o=o toupper(substr(a[w],1,1)) substr(a[w],2)};print o}'`.wiki" + echo >> Makefile + echo $outname: ../mdoc2wiki.awk $f >> Makefile + echo " awk -f ../mdoc2wiki.awk < $f > $outname" >> Makefile + all="$all $outname" done done echo $all >>Makefile @@ -68,3 +110,7 @@ cd .. (cd text && make) # Format all of the manpages to PDF (cd pdf && make) +# Format all of the manpages to HTML +(cd html && make) +# Format all of the manpages to Google Wiki syntax +(cd wiki && make) diff --git a/doc/wiki/.ignore_me b/doc/wiki/.ignore_me new file mode 100644 index 00000000..d285484d --- /dev/null +++ b/doc/wiki/.ignore_me @@ -0,0 +1,2 @@ +*** PLEASE DO NOT DELETE THIS FILE! *** +This file is used to track an otherwise empty directory in git. -- cgit v1.2.1