discuss: Revision History, Revisited (Again)
Subject:
Re: Revision History, Revisited (Again)
From:
Tabatha Marshall ####@####.####
Date:
23 Jan 2004 20:24:38 -0000
Message-Id: <1074889446.27767.36.camel@mysticchild>
On Fri, 2004-01-23 at 10:28, Mendel Cooper wrote:
> On Fri, 23 Jan 2004, Emma Jane Hogbin wrote:
>
> > On Thu, Jan 22, 2004 at 09:25:09PM -0700, Mendel Cooper wrote:
> > > As stated in previous posts of mine, I adopted the <bridgehead> tag for use in
> > > burying the revision history in an appendix. Unfortunately, that particular
> > > tag has some problems.
> >
> > Where exactly are you using the <bridgehead> tag? Is this in the original
> > DocBook document, or in the final (output) HTML?
>
> I was using the <bridghead> tag in the DocBook source, and in an appendix.
>
>
> > The revision history is REQUIRED meta data in the DocBook. I'm currently
> > working with the OAI <www.openarchives.org> community to have the LDP
> > documents included in their repository. The OAI requires DublinCore
> > meta-data, which will need to be mapped onto the DocBook/LinuxDoc meta-data.
> >
> > The revhistory maps onto the "modified" DC element. If it is not stored
> > correctly in the DocBook then I/we/OAI will run into major problems
> > getting the documents submitted.
>
> Whoa! What this means is that I'll restore a truncated revision history,
> with appropriate tags, at the front of the book, and keep the bulk of
> it in an appendix. That way everyone should be happy.
Yep, a popular thread, this revhistory stuff!
I know there has been feedback for and against the use of the
revhistory, and the main reason for this (from what I've read) is
because of how much space it can take up on a document that's been
revised many times.
For those who are uncomfortable with the space consumption, keeping at
least one or two of the most recent rev entries at the top and storing
the rest in an appendix, like you suggest above, is probably the
cleanest way of handling it.
Docs written in Linuxdoc markup I'm not so sure about. I don't know how
OAI would handle the lack of meta data that we find in most of these
documents. With changelogs/revisions only entered as comments, I'm not
sure if this is something they can work with. It does cause me some
concern, in that I'm worried some valuable docs might get overlooked
because of the markup structure.
I don't want to stir things up about the types of markup and their
merits or detriments. But we do need a revhistory in the proper place.
Ideally, DocBook would fix the revhistory so it could appear within an
appendix or another backmatter section. However, the structure of
DocBook documents has become a de facto standard, and until DocBook's
makers change the standards to something else, we should be using it as
it was designed to be used. This allows us to be interoperable with
other organizations that may want to use or contribute to our documents.
Tab
--
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
