[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">
   </author>
 * <date>v1.0, DD MMM YYYY</date>
   <abstract>
     brief description of what the document covers
   </abstract>

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

---

if DocBook:

 <artheader>

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

   <author>
      <firstname>first_name</firstname>
      <surname>last_name</surname>
      <affiliation>
         <address>
            <email>email_address</email>
         </address>
      </affiliation>
   </author>

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

   <pubdate>DD MMM YYYY</pubdate>

   <revhistory>
     <revision>
       <revnumber>v2.0</revnumber>
       <date>DD MMM YYYY</date>
     </revision>

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

   <abstract>
     <para>
       brief description of the document
     </para>
   </abstract>

  </artheader>

---

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.

r,

-- 
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