Date: Sat, 27 May 2000 16:40:15 +0000 From: Nik Clayton <nik@freebsd.org> To: Jim Mock <jim@luna.cdrom.com> Cc: Thomas Kovacs <tom@thomaskovacs.com>, doc@FreeBSD.ORG, nik@FreeBSD.org Subject: Re: Documentation dating Message-ID: <20000527164015.A46877@kilt.nothing-going-on.org> In-Reply-To: <20000524153058.B29447@luna.cdrom.com>; from jim@luna.cdrom.com on Wed, May 24, 2000 at 03:30:58PM -0700 References: <000801bfc5d9$e84256a0$359dfed8@kovacs> <20000524153058.B29447@luna.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, May 24, 2000 at 03:30:58PM -0700, Jim Mock wrote: > [I've Cc'd Nik Clayton on this so we can get his feedback and he doesn't > have to wade through the other -docs messages to get to it.] FWIW, this won't make a difference. ~/.procmailrc is ordered so that anything list specific goes in to the list's file. I only see it in the nik@freebsd.org mailbox if that's the only address it was sent to. But, I'm religious about checking stuff in -doc, so no worries there. > On Wed, 24 May 2000 at 16:43:44 -0700, Thomas Kovacs wrote: > > First off I want to say the documentation you provide is EXCELLENT! I > > have found it extremely helpful and am grateful for all the effort > > contributors have put in to it. I'm pretty experienced with writing > > documentation and when I get better experienced with FreeBSD, I would > > eventually like to help with the documentation project. > > Thanks. I think I speak for all of us when I say that. Indeed. We will also welcome any documentation you'd like to contribute (or suggestions/fixes to the existing documentation). [ quoting kept for context ] > > As a suggestion, would it be possible to put the 'last updated' date > > on each document. I like to keep my collection of documents up to date > > and spend quite a bit of time perusing over on-line pages to determine > > whether I have an updated version or not. > > The only thing I see being a problem, is with the handbook, even though > each ``chapter'' has multiple documents, they're really only in one SGML > file (well, one for each chapter). Let me give you an example incase > that doesn't make sense. In this case, I'll use the security chapter > (http://www.FreeBSD.org/handbook/security.html). > > If you look at the URL above, you'll see something like this: > > 8. Security > 8.1. Synopsis > 8.2. Introduction > 8.3. Securing FreeBSD > 8.4. DES, MD5, and Crypt > 8.5. S/Key > 8.6. Kerberos > 8.7. Firewalls > 8.8. OpenSSL > 8.9. IPsec > > Even though there are 9 sections to that chapter, there is only one file > that generates them: > > [jim@luna:~/handbook]$ ls security/ > CVS chapter.sgml > [jim@luna:~/handbook]$ > > I guess what I'm getting at is that I'm not sure we can do something > like the other FreeBSD.org web pages (with a ``Last modified: <date>'' > sort of thing at the bottom) because of this. This is main reason why > I've Cc'd Nik -- maybe he knows of a way to do it that I'm missing. All > in all though, I think this is a decent idea and wouldn't mind seeing it > implemented. It's implementable, but you've hit the nail of the problem on the head above. To continue to use the security chapter as an example, if someone makes a change to section 8.9 (IPSec), I don't see a way to easily note that the change only affected that section of the chapter. We could break the chapter.sgml files down in to even smaller files, but that's a lot of work for not a lot of benefit. A couple of solutions spring to mind. However, neither of these are that great, and I don't really have the time to implement the first one, so it's up to someone else doing the coding. 1. We could use processing instructions at the top of each chapter.sgml file. You won't see a discussion of processing instructions in the FDP Primer, largely because I've never used them in anger. From memory (and I might be a bit rusty here), we could do something like this <?date $Date$ ?> <?source $Source$ ?> The stylesheets could then be extended to emit something like the following at the top of each .html file generated (I doubt we'd do this for any other format). The SGML source for this page was last edited on _date_. See the _repository log_ for more information about the change. Where "_date_" is the date of the change, and "_repository log_" is a link to http://www.freebsd.org/cgi/cvsweb/cgi/doc/... as necessary. This is feasible, but requires some coding changes to the stylesheets (which, as I say, I don't have the time to consider). It will also complicate the build process somewhat -- we currently use the HTML output format to generate the plain text and Palm versions of the documentation, and I don't think that links like this are appropriate for those formats -- so we'd need an additional HTML-making step in a couple of the targets to produce HTML files without that text. 2. If you take a look at a DocBook reference (such as Norm Walsh's DocBook Guide, see http://www.docbook.org/) you'll see that most of the sectional elements have an equivalent *Info element. For example Book -> BookInfo Article -> ArtHeader [1] Chapter -> DocInfo [2] Sect1 -> Sect1Info Sect2 -> Sect2Info ... -> ... [1] ArtHeader is renamed to ArticleInfo in DocBook 4.0 [2] No idea what the DocBook committee were thinking of here Each one of these can contain a Date element. The DTD says nothing about the content of the Date element, so we could have something like <chapter> <docinfo> <date>1st May 2000</date> </docinfo> <title>My chapter</title> <para>...</para> <sect1> <!-- This section has been edited more recently --> <sect1info> <date>1st June 2000</date> </sect1info> <title>My section</title> <para>...</para> </sect1> </chapter> It's then up to the stylesheets to do the right thing with this information. This approach has a few benefits to the previous one: 1. It doesn't involve adding any more FreeBSD specific kludges to the documentation generation method. 2. It works on documents that are still one big .sgml file, like the FAQ, or the Porter's Handbook. 3. Elements like Author and AuthorGroup are valid inside a *Info element, which means that our earlier discussion of how to correctly give credit for people who were the original authors of chunks of documentation which has since been revised is simple, as you just do <chapter> <docinfo> <authorgroup> <author> <firstname>Sean</firstname> <surname>Kelly</surname> <affiliation> <address><email>kelly@ad1440.net</email></address> </affiliation> <contrib>Wrote the initial version of this chapter, provided the majority of the examples.</contrib> </author> <author> <firstname>Jim</firstname> <surname>Mock</firstname> <affiliation> <address><email>jim@FreeBSD.org</email></address> </affiliation> <contrib>Edited and updated the chapter in preparation for producing the commercially printed FreeBSD Handbook.</contrib> </author> </authorgroup> <date>Nth MMMM, YYYY</date> </docinfo> ... </chapter> 4. We get to choose when a change is flagged as being significant. For example, a simple markup or whitespace change would still bump the CVS $Date$, but we can exercise our judgement, and would (I assume) not bump the Date value for those sorts of changes. it also has a disadvantage. 1. It's not automatic, people would have to remember to update the contents of the Date element by hand. We can't just do <date>$Date$</date>, as our files aren't split up small enough to make that possible. Comments? N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000527164015.A46877>