Attached is a file that supplies boilerplate instructions for reporting errors/patches with a document.
Also attached is a patch to my Stateless Linux tutorial which pulls in the file and uses it, with the various sub-entities given sane definitions.
You can see a usage of this file in an unofficial copy of that tutorial, located here: http://people.redhat.com/dmalcolm/stateless/stateless-linux-HOWTO- en/#errata-tip
I propose adding the first file as "fedora-docs/common/errata-en.xml"
Any thoughts/rewrites? Perhaps the heading should read "About This Document" instead?
Dave Malcolm
On Wed, 2004-11-17 at 13:59, David Malcolm wrote:
Attached is a file that supplies boilerplate instructions for reporting errors/patches with a document.
This is a stellar idea, thanks!
I suggest a few changes, new file attached.
* Added a <!-- comment --> explaining how to obtain and format the URL from bugzilla/
* Some fill-column because I can't help myself. :)
* Changed the <screen> code to match the current FDP style (flush left, <command> on same line, not in <para> block).
I propose adding the first file as "fedora-docs/common/errata-en.xml"
Recommend an RFE bug report.
Might also want to patch fedora-entities-en.xml to have it make the entity declaration:
<!ENTITY ERRATA-TIP-EN SYSTEM "errata-en.xml">
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.
________________________________________________________________________ - Karsten
On Wed, 2004-11-17 at 16:39 -0800, Karsten Wade wrote:
On Wed, 2004-11-17 at 13:59, David Malcolm wrote:
Attached is a file that supplies boilerplate instructions for reporting errors/patches with a document.
This is a stellar idea, thanks!
I suggest a few changes, new file attached.
Thanks!
- Added a <!-- comment --> explaining how to obtain and format the URL
from bugzilla/
Good idea.
- Some fill-column because I can't help myself. :)
Fair enough.
- Changed the <screen> code to match the current FDP style (flush left,
<command> on same line, not in <para> block).
OK
I propose adding the first file as "fedora-docs/common/errata-en.xml"
Recommend an RFE bug report.
Done, as this one: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=139931
Should this go on a tracker bug somewhere?
Might also want to patch fedora-entities-en.xml to have it make the entity declaration:
<!ENTITY ERRATA-TIP-EN SYSTEM "errata-en.xml">
Would doing this require that any files using fedora-entities-en.xml define the various entities referred to in errata-en.xml ? (and hence break all the existing docs, until they get fixed?)
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" ?
- Karsten
-- fedora-docs-list mailing list fedora-docs-list@redhat.com To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
On Thu, 2004-11-18 at 12:45, David Malcolm wrote:
On Wed, 2004-11-17 at 16:39 -0800, Karsten Wade wrote:
Done, as this one: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=139931
Should this go on a tracker bug somewhere?
I don't think there is one, just falls in the "all open fedora-docs bugs" category.
Might also want to patch fedora-entities-en.xml to have it make the entity declaration:
<!ENTITY ERRATA-TIP-EN SYSTEM "errata-en.xml">
Would doing this require that any files using fedora-entities-en.xml define the various entities referred to in errata-en.xml ? (and hence break all the existing docs, until they get fixed?)
Good question. I _think_ it would only come into play if explicitly called by the document. Here's a test.
I added this to my fedora-entities-en.xml:
<!ENTITY ABOUT-DOC-EN SYSTEM "about-doc-en.xml">
then built a document without any error.
It also validated:
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).
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?
- Karsten
On Thu, 2004-11-18 at 16:26 -0800, Karsten Wade wrote:
On Thu, 2004-11-18 at 12:45, David Malcolm wrote:
On Wed, 2004-11-17 at 16:39 -0800, Karsten Wade wrote:
Done, as this one: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=139931
Should this go on a tracker bug somewhere?
I don't think there is one, just falls in the "all open fedora-docs bugs" category.
Might also want to patch fedora-entities-en.xml to have it make the entity declaration:
<!ENTITY ERRATA-TIP-EN SYSTEM "errata-en.xml">
Would doing this require that any files using fedora-entities-en.xml define the various entities referred to in errata-en.xml ? (and hence break all the existing docs, until they get fixed?)
Good question. I _think_ it would only come into play if explicitly called by the document. Here's a test.
I added this to my fedora-entities-en.xml:
<!ENTITY ABOUT-DOC-EN SYSTEM "about-doc-en.xml">
then built a document without any error.
It also validated:
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.
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)
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 :-)
Dave
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. :)
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
- 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
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@redhat.com To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
On Tue, 2004-11-30 at 21:44 -0500, Tammy Fox wrote:
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?
My brain is unfreezing a bit here ... I recall that in fact Mark Johnson did a draft that included an Introduction with much of such information of ... let's see ...
http://people.redhat.com/mjohnson/docs/fedora/docbook-emacs- quickstart/index.html#about
We could include the CVS bit as a section within this section.
- Karsten
-
David Malcolm -
Karsten Wade -
Tammy Fox