* docbook2mdoc: Improve (and fix) manpage and index page.
@ 2014-04-02 12:27 kristaps
0 siblings, 0 replies; only message in thread
From: kristaps @ 2014-04-02 12:27 UTC (permalink / raw)
To: source
Log Message:
-----------
Improve (and fix) manpage and index page.
Remove now-trivial examples.
Modified Files:
--------------
docbook2mdoc:
Makefile
docbook2mdoc.1
docbook2mdoc.c
index.xml
Removed Files:
-------------
docbook2mdoc:
as.xml
iovec.xml
ls.xml
printf.xml
Revision Data
-------------
--- ls.xml
+++ /dev/null
@@ -1,33 +0,0 @@
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<refentry id="ls">
-
- <refmeta>
- <refentrytitle>ls</refentrytitle>
- <manvolnum>1</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>ls</refname>
- <refpurpose>list contents of a directory</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>/usr/bin/ls</command>
- <arg choice="opt">
- <option>aAbcCdfFgilLmnopqrRstux1</option>
- </arg>
- <arg choice="opt" rep="repeat">file</arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1><title>Description</title>
- <para>
- For each file that is a directory, <command>ls</command> lists the contents of
- the directory; for each file that is an ordinary file, <command>ls</command>
- repeats its name and any other information requested.
- </para>
- <para>...</para>
- </refsect1>
-</refentry>
--- iovec.xml
+++ /dev/null
@@ -1,50 +0,0 @@
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<refentry id="iovec">
-
- <refmeta>
- <refentrytitle>iovec</refentrytitle>
- <manvolnum>9S</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>iovec</refname>
- <refpurpose>data storage structure for I/O using uio</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <synopsis>
- #include <sys/uio.h>
- </synopsis>
- </refsynopsisdiv>
-
- <refsect1><title>Interface Level</title>
- <para>
- Architecture independent level 1 (DDI/DKI).
- </para>
- </refsect1>
-
- <refsect1><title>Description</title>
-
- <para>
- An <structname>iovec</structname> structure describes a data
- storage area for transfer in a
- <citerefentry><refentrytitle>uio</refentrytitle>
- <manvolnum>9S</manvolnum>
- </citerefentry>
- structure. Conceptually,
- it may be thought of as a base address and length specification.
- </para>
-
- </refsect1>
- <refsect1><title>Structure Members</title>
-
- <programlisting>
- caddr_t iov_base; /* base address of the data storage area */
- /* represented by the iovec structure */
- int iov_len; /* size of the data storage area in bytes */
- </programlisting>
-
- <para>...</para>
- </refsect1>
-</refentry>
Index: docbook2mdoc.1
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/docbook2mdoc/docbook2mdoc.1,v
retrieving revision 1.1
retrieving revision 1.2
diff -Ldocbook2mdoc.1 -Ldocbook2mdoc.1 -u -p -r1.1 -r1.2
--- docbook2mdoc.1
+++ docbook2mdoc.1
@@ -21,7 +21,7 @@
.Nm docbook2mdoc
.Nd Convert DocBook refentry to mdoc
.Sh SYNOPSIS
-.Nm docbook2man
+.Nm docbook2mdoc
.Op Ar file
.Sh DESCRIPTION
The
@@ -33,12 +33,18 @@ generates
.Xr mdoc 7
from the
.Aq refentry
-section of DocBook source.
+section of DocBook source, ignoring other sections.
If unspecified or
.Ar \&- ,
.Ar file
is taken to be standard input.
It accepts no arguments.
+.Pp
+.Nm
+supports only well-formed XML DocBook V4.x until V5.1.
+SGML DocBook documents may be parsed unless they contain SGML-specific
+constructs, such as empty end tags
+.Li </> .
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
@@ -61,6 +67,11 @@ was written by
The
.Nm
utility is experimental.
-As such, only a small subset of the
+As such, only a modest subset of the
.Aq refentry
domain is accepted.
+.Pp
+The output
+.Xr mdoc 7
+could be much nicer: trailing spaces, superfluous space removal,
+new-line new-sentence, and other niceties are not used.
Index: docbook2mdoc.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/docbook2mdoc/docbook2mdoc.c,v
retrieving revision 1.30
retrieving revision 1.31
diff -Ldocbook2mdoc.c -Ldocbook2mdoc.c -u -p -r1.30 -r1.31
--- docbook2mdoc.c
+++ docbook2mdoc.c
@@ -335,15 +335,17 @@ xml_elem_start(void *arg, const XML_Char
if (0 == strcmp(*att, attrkeys[key]))
break;
if (ATTRKEY__MAX == key) {
- fprintf(stderr, "%s:%zu:%zu: unknown "
- "attribute \"%s\"\n", ps->fname,
+ fprintf(stderr, "%s:%zu:%zu: warning: "
+ "unknown attribute \"%s\"\n",
+ ps->fname,
XML_GetCurrentLineNumber(ps->xml),
XML_GetCurrentColumnNumber(ps->xml),
*att);
continue;
} else if ( ! isattrkey(node, key)) {
- fprintf(stderr, "%s:%zu:%zu: bad "
- "attribute \"%s\"\n", ps->fname,
+ fprintf(stderr, "%s:%zu:%zu: warning: "
+ "bad attribute \"%s\"\n",
+ ps->fname,
XML_GetCurrentLineNumber(ps->xml),
XML_GetCurrentColumnNumber(ps->xml),
*att);
@@ -353,8 +355,9 @@ xml_elem_start(void *arg, const XML_Char
if (0 == strcmp(*(att + 1), attrvals[val]))
break;
if (ATTRVAL__MAX != val && ! isattrval(key, val)) {
- fprintf(stderr, "%s:%zu:%zu: bad "
- "value \"%s\"\n", ps->fname,
+ fprintf(stderr, "%s:%zu:%zu: warning: "
+ "bad attribute value \"%s\"\n",
+ ps->fname,
XML_GetCurrentLineNumber(ps->xml),
XML_GetCurrentColumnNumber(ps->xml),
*(att + 1));
--- as.xml
+++ /dev/null
@@ -1,32 +0,0 @@
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-
-<reference><title>Reference Pages</title>
-
- <refentry>
- <refnamediv>
- <refdescriptor>GNU as</refdescriptor>
- <refname>as</refname>
- <refpurpose>the portable GNU assembler</refpurpose>
- </refnamediv>
- <refsynopsisdiv><title>SYNOPSIS</title>
- <synopsis>...</synopsis>
- </refsynopsisdiv>
- <refsect1><title>DESCRIPTION</title>
- <para>...</para>
- </refsect1>
- </refentry>
-
- <refentry>
- <refnamediv>
- <refname>awk</refname>
- <refpurpose>pattern scanning and text processing language</refpurpose>
- </refnamediv>
- <refsynopsisdiv><title>SYNOPSIS</title>
- <synopsis>...</synopsis>
- </refsynopsisdiv>
- <refsect1><title>DESCRIPTION</title>
- <para>...</para>
- </refsect1>
- </refentry>
-</reference>
Index: index.xml
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/docbook2mdoc/index.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -Lindex.xml -Lindex.xml -u -p -r1.6 -r1.7
--- index.xml
+++ index.xml
@@ -35,7 +35,7 @@
<article>
<p>
The <span class="nm">docbook2mdoc</span> utility is a converter from <a
- href="http://www.oasis-open.org/docbook/">DocBook</a> into <a
+ href="http://www.oasis-open.org/docbook/">DocBook</a> V4.x and v5.x XML into <a
href="http://www.openbsd.org/cgi-bin/man.cgi?query=mdoc&sektion=7">mdoc</a>.
Unlike most DocBook utilities, it's a standalone <a rel="license"
href="https://www.isc.org/downloads/software-support-policy/isc-license/">ISC</a>-licensed ISO C utility
@@ -44,23 +44,17 @@
installed by default on most systems.
</p>
<p>
- <span class="nm">docbook2mdoc</span> is <em>very</em> experimental: it probably won't work with your manual
- without improvement.
- However, it does work with the DocBook reference manuals (minimally rendered here with <a
- href="http://mdocml.bsd.lv">mandoc</a> -Thtml): <a href="printf.html">printf</a>, <a
- href="ls.html">ls</a>, <a href="as.html">as</a>, <a href="iovec.html">iovec</a>.
- </p>
- <p>
- Contact <a href="http://kristaps.bsd.lv">Kristaps</a> with questions, but please make sure any formatting issue
- hasn't already been covered in the <a href="docbook2mdoc.1.html">manual</a>.
+ <span class="nm">docbook2mdoc</span> is experimental: it still has many missing elements.
+ However, it works with the DocBook reference examples and documents found in the wild.
+ Contact <a href="http://kristaps.bsd.lv">Kristaps</a> with questions or missing nodes; or better yet, download
+ the source and add new elements yourself as described in the <a href="README.txt">README</a>.
</p>
<h2>
New in version @VERSION@...
</h2>
<p>
- Allow for more node types as found in <a href="http://www.catb.org/~esr/doclifter/">doclifter</a> output.
- Add rudimentary support for <code><table></code> as a list-of-lists.
- Still lots of work to be done before accepting enough DocBook to be useful...
+ Now supports all tags as found in the <a href="http://refdb.sourceforge.net/">RefDB</a> tool, which claims to
+ have extensive DocBook documentation.
</p>
</article>
<footer>
Index: Makefile
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/docbook2mdoc/Makefile,v
retrieving revision 1.10
retrieving revision 1.11
diff -LMakefile -LMakefile -u -p -r1.10 -r1.11
--- Makefile
+++ Makefile
@@ -1,16 +1,15 @@
-VERSION = 0.0.6
+VERSION = 0.0.7
CFLAGS += -g -W -Wall -Wstrict-prototypes -Wno-unused-parameter -Wwrite-strings
-BUILT = printf.html iovec.html ls.html as.html
WWWPREFIX = /usr/vhosts/mdocml.bsd.lv/www/htdocs/docbook2mdoc
docbook2mdoc: docbook2mdoc.o rules.o
$(CC) -o $@ docbook2mdoc.o rules.o -lexpat
-www: index.html docbook2mdoc.1.html docbook2mdoc-$(VERSION).tgz $(BUILT)
+www: index.html docbook2mdoc.1.html docbook2mdoc-$(VERSION).tgz README.txt
installwww: www
mkdir -p $(WWWPREFIX)/snapshots
- install -m 0444 index.html docbook2mdoc.1.html $(BUILT) $(WWWPREFIX)
+ install -m 0444 index.html docbook2mdoc.1.html README.txt $(WWWPREFIX)
install -m 0444 docbook2mdoc-$(VERSION).tgz $(WWWPREFIX)/snapshots
install -m 0444 docbook2mdoc-$(VERSION).tgz $(WWWPREFIX)/snapshots/docbook2mdoc.tgz
@@ -30,21 +29,10 @@ index.html: index.xml
docbook2mdoc.1.html: docbook2mdoc.1
mandoc -Thtml docbook2mdoc.1 >$@
-printf.html:
- ./docbook2mdoc printf.xml | mandoc -Thtml > $@
-
-iovec.html:
- ./docbook2mdoc iovec.xml | mandoc -Thtml > $@
-
-ls.html:
- ./docbook2mdoc ls.xml | mandoc -Thtml > $@
-
-as.html:
- ./docbook2mdoc as.xml | mandoc -Thtml > $@
-
-$(BUILT): docbook2mdoc
+README.txt: README
+ cp README $@
clean:
rm -f docbook2mdoc docbook2mdoc.o rules.o
rm -rf docbook2mdoc.dSYM
- rm -f $(BUILT) index.html docbook2mdoc.1.html docbook2mdoc-$(VERSION).tgz
+ rm -f index.html docbook2mdoc.1.html docbook2mdoc-$(VERSION).tgz README.txt
--- printf.xml
+++ /dev/null
@@ -1,53 +0,0 @@
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<refentry id="printf">
-
- <refmeta>
- <refentrytitle>printf</refentrytitle>
- <manvolnum>3S</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>printf</refname>
- <refname>fprintf</refname>
- <refname>sprintf</refname>
- <refpurpose>print formatted output</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
-
- <funcsynopsis>
- <funcsynopsisinfo>
- #include <stdio.h>
- </funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>printf</function></funcdef>
- <paramdef>const char *<parameter>format</parameter></paramdef>
- <paramdef>...</paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fprintf</function></funcdef>
- <paramdef>FILE *<parameter>strm</parameter></paramdef>
- <paramdef>const char *<parameter>format</parameter></paramdef>
- <paramdef>...</paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>sprintf</function></funcdef>
- <paramdef>char *<parameter>s</parameter></paramdef>
- <paramdef>const char *<parameter>format</parameter></paramdef>
- <paramdef>...</paramdef>
- </funcprototype>
- </funcsynopsis>
-
- </refsynopsisdiv>
-
- <refsect1><title>Description</title>
- <para>
- <function>printf</function> places output on the standard
- output stream stdout.
- </para>
- <para>...</para>
- </refsect1>
-</refentry>
--
To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2014-04-02 12:27 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-04-02 12:27 docbook2mdoc: Improve (and fix) manpage and index page kristaps
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).