Adding boilerplate errata/CVS instructions

[Tammy Fox]

On Fri, Nov 19, 2004 at 12:49:20PM -0800, Karsten Wade wrote:
> On Thu, 2004-11-18 at 16:54, David Malcolm wrote: 
> > On Thu, 2004-11-18 at 16:26 -0800, Karsten Wade wrote:
> 
> > > cd /home/kwade/Documents/projects/fedora/fedora-docs/selinux-apache/
> > > nsgmls -wxml -s /home/kwade/lib/psgmlx-0.5/lib/xml.dcl
> > > selinux-apache-en.xml
> > > nsgmls:/home/kwade/lib/psgmlx-0.5/lib/xml.dcl:1:W: SGML declaration was
> > > not implied
> > > 
> > > SGML validation finished at Thu Nov 18 16:24:42
> > > 
> > > FWIW, that's the way it normally appears when I validate (in Emacs using
> > > C-c C-v).
> > 
> > OK, great; good idea.  Is xmllint happy with such a setup?  If so, then
> > the ABOUT-DOC-EN probably _should_ get added to the main entities file.
> 
> As far as I can tell, it works fine.  I just ran xmllint against it
> (without options), with only FEDORA-ENTITIES-EN and the various
> PUBLISHED-HTML-URL etc. defined in a document, and it validates, builds,
> and does not error.
> 
> > > > > > Any thoughts/rewrites?  Perhaps the heading should read "About This
> > > > > > Document" instead?
> > > > > 
> > > > > Yes, that is more of an accurate title.  Changed that in the attachment.
> > > > 
> > > > Perhaps the file should have a different name; perhaps
> > > > "about-this-document-en.xml" ?
> > > 
> > > How about about-doc-en.xml?
> > Yes, that's much better.
> > 
> > Maybe even "about-fedora-doc-en.xml", to make it clear that this relates
> > to a Fedora doc? (as opposed to RHEL)
> 
> No need, everything is separate ... although it is not improper, and is
> certainly future proofing.  Do as you wish, since I'm wishy-washy. :)
> 

Since it is already part of a module called fedora-docs, adding fedora
to the filename is redundant.


> > Can I go ahead and commit this (assuming I have access rights)?  Or
> > should someone else on the list comment first?  I'm just a lowly desktop
> > developer :-)
> 
> Nah, youse a riter, now.
> 
> I suggest you file a bug (RFE) against fedora-docs (tfox will get it,
> she has write perms and the buck-stops-here for stuff like what goes in
> fedora-docs/common), attach a patch to fedora-entities-en.xml, attach
> the about{-fedora}-doc-en.xml file.  We'll also need to fix the
> fedora-docs/example-tutorial to include the new entity call(s) and
> sample definitions for the 4 entities required by 
> 

I saw your RFE. I think it is a great idea, like the name "About this
Document," and like the name about-doc-en.xml as the filename.

However, I think it would be better as a separate sect1 either at the
beginning or the end of the document. Tips are supposed to be shorter
pieces of information called out to help the reader accomplish a task.

I've seen many other documents with an About this Document section,
and they have always been separate sections.

Having a separate section also allows us to have a common place for
the "Acknowledgements" and "Revision History" sections under this
sect1 as sect2s.

Thoughts?

Tammy

> - Karsten
> --
> Karsten Wade, RHCE, Tech Writer
> a lemon is just a melon in disguise
> http://people.redhat.com/kwade/
> gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41
> 
> -- 
> fedora-docs-list mailing list
> fedora-docs-list at redhat.com
> To unsubscribe: 
> http://www.redhat.com/mailman/listinfo/fedora-docs-list

--