Hardening Doc Preview

[Karsten Wade]

On Sat, 2004-09-04 at 06:27, tuxxer wrote:

> On that note, is there a way to insert a "default disclaimer" stating
> that it's a draft?  I've tried creating an <!ENTITY ... > called
> 'DRAFTNOTICE', but `make html` fails everytime I add it.
> 
> Included below it the text for the DRAFTNOTICE...

Hey, that's a nice idea.  I like that.  Inclusion of a draft notice like
this is a good must-have, and Mark's watermark is a good nice-have.  I
am definitely going to use the watermark for whenever I am concerned
that a reader will think looks_nice == completed_document. :)


> DRAFTNOTICE TEXT:
> 
> <!-- $Id: $ -->
> 
> <note>
>   <title>Draft Notice:</title>
>   <para>This version of this document is not yet affiliated with the
> Fedora Docs
>   Project.  It is a draft, and may be submitted to the project for
>   review/approval at a later date.  Until that time, that document will
> be
>   receiving constant updates, and may change frequently.
>   </para>
> </note>

+1 on the text and format.

Not sure what the trouble is; your idea should work.  You can call in
any arbitrary bit of legal XML that is kept in a separate file.

* Put the <note/> block into a separate file draftnotice.xml and put it
in fedora-docs/common (where we can all use it, thank you)

* Put an entity in common/fedora-entities-en.xml.  Note that the format
is different when you are calling in a file:

<!ENTITY DRAFTNOTICE SYSTEM "./draftnotice.xml">

* In your XML, you will have to put in the &DRAFTNOTICE; where it is
legal XML, i.e., inside of a <section>.

If you do that, and it works, please do the following to get your idea
into regular usage:

1. 'cd fedora-docs/common'
2. 'cvs diff -du fedora-entities-en.xml | tee
/tmp/fedora-entities-en-tuxxer.patch' (or some such name)
3. If that doesn't work (probably because of a cvs environment
variable), try the following:
 3.1. Before you edit the file, 'cp fedora-entities-en.xml
fedora-entities-en.xml.original'
 3.2. Edit the file, then do 'diff -u fedora-entities-en.xml.original
fedora-entities-en.xml | tee /tmp/fedora-entities-en-tuxxer.patch'
4. File a bug against fedora-docs, set the severity to Enhancement (this
is a Request For Enhancement aka RFE); put the details into the bug
report, make an attachment of the new XML file (draftnotice.xml) and the
patch.

Hmmm ... maybe I should snarf the above description and submit it as a
patch to the Documentation Guide for "How to submit your idea for a
change to Fedora Docs Project." 

;-)

- 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