[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: date formats

On Dec 7,  9:06am, David Merrill wrote:
> Subject: date formats
> The LAG, section 6.1, says that:
> The <pubdate> tag in your header should be in the following format:
> v1.0, 21 April 2000
> This seems strange to me. The version number has nothing to do with
> the date of publication. The example in DocBook:TDG uses only the year
> of publication here, but doesn't give specific enough information to
> know whether this is the recommended usage. Anybody know?
> I take it, literally, to mean that this applies only to the <pubdate>
> tag. What about other date tags, particularly the date in revhistory?
> <revhistory>
>   <revision>
>     <revnumber>1.0</revnumber>
>     <date>27 de janeiro de 2000</date>  <- taken from example.sgml
> This particular example also brings up another wrinkle - language.
> If we are using month names, then they could be in many different
> languages. Using a standard ISO date format would mean fewer
> differences in the dates:
>     <date>2000-01-27</date>
> not to mention being easier to parse in scripts.

As long as we are assured it's YYYY-MM-DD and not YYYY-DD-MM.
I'd advocate using "DD MMM YYYY", where MMM = {Jan, Feb, etc};
no descrepency or confusion.

> Is there already a "standard" in place for this that I'm unaware of?
> If so, let me know and I'll add it into the same section of the LAG as
> the <pubdate> reference. If not, let's set one, please.

The format is (I believe) a hold-over from the linuxdoc DTD. As I read
it, linuxdoc does not have a tag for any sort of version specification
(if one has been added, to a recent snapshot of the linuxdoc-tools,
please lmk).  Therefore, all data is supplied in the <date> tag, as:

    <date>v1.0, 21 April 2000</date>

We carried that over to DocBook, using the <pubdate> tag.
You're right, it's not the best/proper use of the tag; esp.
given the wealth of tags to use in DocBook.

In fact, I'm not so sure <pubdate> needs to be used at all.
Does this represent the current date of the publication, or
the date the document was *initially* published? How does this
coincide with the <date> within a <revision> grouping? I suppose
revisions can occur without publishing, but it would seem like
the very first <revision> entry in the <revhistory> (the latest
revision) would be the accurate date field to use.

In the SGML parsing routines I've built, this is the nastiest part
(as you've seen!). I parse for and use <revision>, <date>,
<pubdate>, etc. - I try to use whatever the author has supplied
(DTD specific).

A recommendation is outlined below; I've extended this as to what
I think would comprise a good/valid MINIMUM set of elements for
a header area for LDP documents:


if linuxdoc:

   <title>title of HOWTO, include "HOWTO" or "mini HOWTO"</title>
   <author>first_name last_name,
       <htmlurl url="mailto:email_address"; name="email_address">
 * <date>v1.0, DD MMM YYYY</date>
     brief description of what the document covers

 * unless a version tag is added; then split version out


if DocBook:


   <title>title of HOWTO, include "HOWTO" or "mini HOWTO"</title>


   <!-- Additional author entries go here -->

   <pubdate>DD MMM YYYY</pubdate>

       <date>DD MMM YYYY</date>

     <!-- Additional, *earlier* revision histories go here -->

       brief description of the document



More tags *could* be used (<othercredit>, <titleabbrev>, <orgname>,
<copyright>, <authorinitials>, <revremark>, etc.) and perhaps
more should be used, but I see this as being a *minimum*  set of
tags that constitute a valid header area.

Please provide comments. As David says, we should get these
guidelines into the style section of the LAG.


Greg Ferguson     - s/w engr / mtlhd         | gferg at sgi.com
SGI Tech Pubs     - http://techpubs.sgi.com/ |
Linux Doc Project - http://www.linuxdoc.org/ | gferg at metalab.unc.edu

To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org