discuss: Revision history at end of document
Subject:
Re: Revision history at end of document
From:
David Lawyer ####@####.####
Date:
15 Jan 2004 03:33:52 -0000
Message-Id: <20040115031509.GA2015@lafn.org>
On Wed, Jan 14, 2004 at 02:22:54PM -0800, Tabatha Marshall wrote:
> On Wed, 2004-01-14 at 14:19, Tabatha Marshall wrote:
>
> > My position on it has always been that it's important to see SOMETHING
> > in the revhistory, if the document is in DocBook.
Why should it be any different than LinuxDoc? The revision history
should be optional in my opinion.
There is a problem with DocBook docs that I've just looked at since they
have neither a version number nor a date except in the revision history.
Also some DocBook docs have long revision histories at the start which
interferes with reading them. One looks at the doc and doesn't even see
the table of contents unless one scrolls down. I think that the
template is part of the problem since the template has no <date> tag (or
the like). In Linuxdoc, both the version number and the date go under
the <date> tag. In DocBook ??? but I suspect it's a lot more
complicated.
> >The number of
> > revisions is another story, which is why I support keeping the
> > latest revision entry at the top and keeping a history of it
> > elsewhere, such as in source >>OR<< an appendix - the only problem
> > with an appendix is that the tags themselves are made to be entered
> > a certain way or they won't work, and some people can't deal with
> > reading source, so I'm not sure how feasible either idea is.
Why not just make it another section? Here's what I do in LinuxDoc
source (history [Change log] is a comment). I'll argue that most all
people can deal with reading this source. Compare it to the obfuscation
of DocBook.
<!doctype linuxdoc system>
<article>
<title> Text-Terminal-HOWTO
<author> David S. Lawyer <url ####@####.####
<date> v1.34, December 2003
<!--
Change log:
v1.34 Dec. 2003: All ~ (tildes) are now in text (formatting problem with Linuxdoc)
v1.33 Nov. 2003: revised setserial section; using minicom with
directly connected terminals
v1.32: Sept. 2003: man page console_codes, name: serial
monitor/console, "init string" rewrite, netrik text browser, new url
for terminfo
v1.31 Jan. 2003: more on printer port, error char. appearance, devfs,
removed all mention of obsolete /dev/cua, pin numbering, new
X-Terminal HOWTO, Hydra date is 1998 (not 1988), edited thin clients
[snip]
David Lawyer
