May 2005 - docs - Fedora mailing-lists

how to generate a pot file for FC-4 release-notes? thx.
by Yuan Yijun 30 May '05

30 May '05

Greetings, I have checked out the release-notes of FC-4 from cvs. Some one suggests me to use xml2po to simplify the translation process. I tried it but it doesn't work. Some xml files are blank, without a root element. Only one of them contains DOCTYPE and xml2po just ignores all the tags in the other files. If I specify *.xml in the command line, xml2po prompts me Traceback (most recent call last): File "/usr/bin/xml2po", line 716, in ? CurrentXmlMode.preProcessXml(doc,msg) File "/usr/share/xml2po/docbook.py", line 142, in preProcessXml root = doc.getRootElement() File "/usr/lib/python2.4/site-packages/libxml2.py", line 4064, in getRootElement if ret is None:raise treeError('xmlDocGetRootElement() failed') libxml2.treeError: xmlDocGetRootElement() failed What should I do to generate a proper pot file? BTW, are there any chinese speakers on this list? -- bbbush ^_^

3 3

Re: release-notes/FC4 kernel.xml,1.3,1.4
by Karsten Wade 30 May '05

30 May '05

I suppose since these are commented out they don't affect anything except ... well, I can't figure what. I'm soooo curious, how do they make editing easier? Is it to keep track of the entities used? BTW, I think your <screen> style is off from the style guidelines ... http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen… Some of your check-ins have funky indenting ... the <para> content is two characters from the left. We all seem to have subtle differences. Not sure how to resolve that. When I get a chance, I'm going to first reformat kernel.xml, then commit, then edit the content, all to make for a saner, happier diff. This worked great, btw. Everyone formed like Voltron, really brought a lot of good content and shine to the relnotes. - Karsten On Mon, 2005-05-30 at 19:27 -0400, Tommy Reynolds wrote: > + > + > +<section id="sn-kernel"> > + <title> > + Linux Kernel > + </title> > + <section id="sn-kernel-lotsa"> > + <title>Version</title> > + <para> > + The &DISTRO; is based on a 2.6.11 kernel. > + &FC; may include additional patches for improvements, bug fixes, or additional features. > + For this reason, the &FC; kernel may not be line-for-line equivalent to the so-called vanilla kernel from the <ulink url="http://ww.kernel.org"><filename>kernel.org</filename></ulink> web site. > + </para> > + <para> > + You may obtain a list of any such patches by using the command on the &FC; package: > + </para> > + <screen width="56"><prompt>$ </prompt><command>rpm</command> <parameter class="option">-qpl</parameter> <filename>kernel-</filename><replaceable><version></replaceable><filename>.src.rpm</filename></screen> > + </section> > + <section id="sn-kernel-flavors"> > + <title>Kernel Flavors</title> > + <para> > + &FC; includes the following kernel builds: > + </para> > + <itemizedlist> > + <listitem> > + <para> > + Native kernel, in both uniprocessor and <abbrev>SMP</abbrev> varieties. > + </para> > + <para> > + Configured sources are available in the <filename>kernel-devel-</filename><replaceable><version></replaceable><filename>.</filename><replaceable><arch></replaceable><filename>.rpm</filename> package. > + </para> > + </listitem> > + <listitem> > + <para> > + Virtual kernel for use with the <wordasword>XEN</wordasword> emulator package. > + </para> > + <para> > + Configured sources are available in the <filename>kernel-xen0-devel-</filename><replaceable><version></replaceable><filename>.</filename><replaceable><arch></replaceable><filename>.rpm</filename> package. > + </para> > + </listitem> > + </itemizedlist> > + <para> > + Sources for both kernel flavors may be installed at the same time. > + The files will be installed into the <filename>/usr/src/kernels/</filename><replaceable><version></replaceable>[<filename>-xen0</filename>]<filename>-</filename><replaceable><arch></replaceable><filename>/</filename> tree. > + Use the command: > + </para> > + <screen width="56"><prompt># </prompt><command>rpm</command> <parameter class="option">-Uvh</parameter> <filename>kernel-devel[-xen0]-</filename><replaceable><version></replaceable><filename>.</filename><replaceable><arch></replaceable><filename>.rpm</filename></screen> > + <para> > + as appropriate. > + </para> > + <tip> > + <title>Following Generic Textbooks</title> > + <para> > + Many of the tutorials, examples, and textbooks about Linux kernel development assume the kernel sources are installed under the <filename>/usr/src/linux</filename> directory. > + If you make a symbolic link, as shown below, you should be able to use those learning materials with the &FC; packages. > + Install the appropriate kernel sources, as shown earlier, and then: > + </para> > + <screen width="56"><prompt># </prompt><command>ln</command> <parameter class="option">-s</parameter> <filename>/usr/src/kernels/kernel-</filename><replaceable><all-the-rest></replaceable> <filename>/usr/src/linux</filename></screen> > + </tip> > + </section> > +  > + <section id="sn-kernel-exploding"> > + <title> > + Preparing for Kernel Development > + </title> > + <para> > + &DISTRO; &DISTROVER; does not include the <filename>kernel-source</filename> package provided by older versions. > + Instead, configured sources are available as described in <xref linkend="sn-kernel-flavors"/>. > + Users that require access to &FC; original kernel sources can find them in the <filename>kernel</filename> <filename>.src.rpm</filename> package. > + To create an exploded source tree from this file, perform the following steps: > </para> > - <tip> > - <title>Source not required to build kernel modules</title> > + <warning> > + <title>These Instructions Refer The Currently-running Kernel!</title> > + <para> > + To simplify the following directions, we have assumed that you want to configure the kernel sources to match your currently-running kernel. > + In the steps below, you must understand that the phrase <wordasword><version></wordasword> refers to the kernel version shown by the: > + </para> > + <screen width="56"><prompt>$ </prompt><command>uname</command> <parameter class="option">-r</parameter></screen> > + <para> > + command. > + </para> > + </warning> > + <procedure id="sn-kernel-exploding-steps"> > + <step> > + <para> > + Obtain the <filename>kernel-<replaceable><version></replaceable>.src.rpm</filename> file from one of the following sources: > + </para> > + <itemizedlist> > + <listitem> > + <para> > + The <filename>SRPMS</filename> directory on the appropriate <wordasword>SRPMS</wordasword> <abbrev>CD</abbrev> <filename>iso</filename> image. > + </para> > + </listitem> > + <listitem> > + <para> > + The FTP site where you got the kernel package. > + </para> > + </listitem> > + <listitem> > + <para> > + By running the following command: > + </para> > + <screen width="56"><prompt># </prompt><command>up2date</command> <parameter class="option">--get-source</parameter> <filename>kernel</filename></screen> > + </listitem> > + </itemizedlist> > + </step> > + <step> > + <para> > + Install <filename>kernel-<replaceable><version></replaceable>.src.rpm</filename> using the command: > + </para> > + <screen width="56"><prompt># </prompt><command>rpm</command> <parameter class="option">-Uvh</parameter> <filename>kernel-</filename><replaceable><version></replaceable><filename>.src.rpm</filename></screen> > + <para> > + This writes the <abbrev>RPM</abbrev> contents into <filename>/usr/src/redhat/SOURCES</filename> and <filename>/usr/src/redhat/SPECS</filename>. > + </para> > + </step> > + <step> > + <para> > + Prepare the kernel sources using the commands: > + </para> > + <screen width="56"><prompt># </prompt><command>cd</command> <filename>/usr/src/redhat/SPECS</filename> > +<prompt># </prompt><command>rpmbuild</command> <parameter class="option">-bp --target $(arch)</parameter> <filename>kernel.spec</filename></screen> > + <para> > + The kernel source tree will be located in the <filename>/usr/src/redhat/BUILD/kernel-</filename><replaceable><version></replaceable> directory. > + It is common practice to move the resulting <filename>linux-</filename><replaceable><version></replaceable> directory to the <filename>/usr/src</filename> tree; while not strictly necessary, we suggest that you do this to match the generally-available documentation. > + </para> > + <screen width="56"><prompt># </prompt><command>cd</command> <filename>/usr/src/redhat/BUILD/kernel-</filename><replaceable><version></replaceable> <filename>/usr/src/</filename> > +<prompt># </prompt><command>mv</command> <filename>linux-</filename><replaceable><version></replaceable> <filename>/usr/src/</filename> > +<prompt># </prompt><command>cd</command> <filename>/usr/src</filename> > +<prompt># </prompt><command>ln</command> <parameter class="option">-s</parameter> <filename>./linux-</filename><replaceable><version></replaceable> <filename>linux</filename> > +<prompt># </prompt><command>cd</command> <filename>/usr/src/linux</filename></screen> > + </step> > + <step> > + <para> > + The configurations for the specific kernels shipped in &DISTRO; &DISTROVER; are in the <filename>configs/</filename> directory. > + For example, the i686 SMP configuration file is named <filename>configs/kernel-<replaceable><version></replaceable>-i686-smp.config</filename>. > + Issue the following command to place the desired configuration file in the proper place for building: > + </para> > + <screen width="56"><prompt># </prompt><command>cp</command> <filename>configs/</filename><replaceable><desired-config-file></replaceable> <filename>.config</filename></screen> > + </step> > + <step> > + <para> > + Issue the following command: > + </para> > + <screen width="56"><prompt># </prompt><command>make oldconfig</command></screen> > + </step> > + </procedure> > + <para> > + You can then proceed as usual. > + </para> > + </section> > + <section id="sn-kernel-3rdparty"> > + <title>Building Only Kernel Modules</title> > <para> > - An exploded source tree is <emphasis>not</emphasis> required to > - build kernel modules against the currently in-use kernel. > + An exploded source tree is <emphasis>not</emphasis> required to build a kernel module, such as your own device driver, against the currently in-use kernel. > </para> > <para> > - For example, to build the <filename>foo.ko</filename> module, > - create the following file (named <filename>Makefile</filename>) in > - the directory containing the <filename>foo.c</filename> file: > + For example, to build the <filename>foo.ko</filename> module, create the following <filename>Makefile</filename> in the directory containing the <filename>foo.c</filename> file: > </para> > -<screen> > -<computeroutput> > -obj-m := foo.o > +<programlisting width="56"> > +obj-m := foo.o > > -KDIR := /lib/modules/$(shell uname -r)/build > -PWD := $(shell pwd) > +KDIR := /lib/modules/$(shell uname -r)/build > +PWD := $(shell pwd) > > default: > - $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules > -</computeroutput> > -</screen> > - <para> > + $(MAKE) -C $(KDIR) M=$(PWD) modules > +</programlisting> > + <para> > Issue the <command>make</command> command to build the > <filename>foo.ko</filename> module. > </para> > - </tip> > + </section> > + <section id="sn-kernel-coop"> > + <title>Userspace Dependancies on the Kernel</title> > + <para> > + &DISTRO; adds support for clustered systems. > + This requires a special kernel that works in conjunction with some user-space utilities, such as management daemons. > + Consequently, to remove such a kernel, perhaps after an update, you <emphasis>cannot</emphasis> simply use the <command>rpm -e kernel-</command><replaceable><version></replaceable> command as in earlier distributions because these userspace packages depend on the kernel package. > + You may either list both the kernel package and its userspace dependant packages on the <command>rpm -e</command> command, or you may wish to use the <command>yum remove kernel-</command><replaceable><version></replaceable> command instead since <command>yum</command> automatically removes dependant packages if necesssary. > + </para> > + </section> > </section> > <!-- > Local variables: > > -- > Fedora-docs-commits mailing list > Fedora-docs-commits(a)redhat.com > https://www.redhat.com/mailman/listinfo/fedora-docs-commits -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

2 1

for writing relnotes beats
by Karsten Wade 26 May '05

26 May '05

If you are writing a relnotes beat, you can write directly into the XML in CVS. The files in release-notes/FC4/ are mainly ready to go. I still have to include all of the information from FC4 tests, the current content in those XML files is for FC3 (the source I used). Feel free to include the test changes yourself that are in release-notes/fc4- relnotes. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

1 1

call for release notes for FC4
by Karsten Wade 26 May '05

26 May '05

Now is your final time to get your release note requests in for Fedora Core 4. Current version of the release notes is available here: http://fedora.redhat.com/docs/beta/release-notes-en/fc4-relnotes This version is in plain text. Here is how you can send in release notes: * Use this pre-filled bugzilla template (preferred method): http://tinyurl.com/exov3 -- OR -- * Send email with details to relnotes(a)fedoraproject.org . The latter will likely have a bug created to track discussion and resolution. Please file a bug instead in the first place. Release notes are now being handled by a team through the Fedora Documentation Project. Individuals or small groups handle a particular relnotes beat. Your note will be assigned to a writer on your beat. All release note requests are available through the tracking bugzilla number: https://bugzilla.redhat.com/beta/showdependencytree.cgi?id=151189 You can read more about the beats, which are subject to change as we develop this process. Note that many of the current writers are temporary assignments only. http://fedoraproject.org/wiki/DocsProject/ReleaseNotes/Beats We are looking for ongoing relnotes beat writers. If you or anyone else is interested, please visit: http://www.fedoraproject.org/wiki/DocsProject/NewWriters Thanks - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

2 3

OpenOffice.org 1.9 (FC4t3)
by Paul W. Frields 26 May '05

26 May '05

FWIW, I have been playing a little bit with the FC4test3 build, and as of last night, OO.o now will create DocBook XML 4.1.2 documents "out of the box," as long as the Java environment is installed. This could be a great step forward for our project since it would allow non-Emacs, non- XML folks to write documents. If I use OO.o styles as follows, the XSLT stuff makes valid DocBook XML: OO.o format: (OO.o styles are in [] brackets) -=-=-=- [Heading1]My Title[/Heading1] [Body text]Some text.[/Body text] [Heading2]Another Chunk[/Heading2] [Body text]Some more text.[/Body text] Produces this DocBook XML 4.1.2 text (although the indentation may not match PSGML): -=-=-=- <sect1> <title>My Title</title> <para>Some text.</para> <sect2> <title>Another Chunk</title> <para>Some more text.</para> </sect2> </sect1> It's a great start, especially considering what a confusing PITA it is for a newbie to install any DocBook functionality in OO.o 1.1.x. I haven't fully investigated yet how well the XSLT stuff in OO.o works to import documents. In other words, will it serve well for collaboration between people who are not using the same tool? I don't know, but the barrier certainly seems significantly lower for first-time contributors, if they prefer to write in a full-featured WYSIWYG word processor. Next up -- and after the IG is out and the DocG is revving up -- I may look into creating an OO.o style template that would be even more WYSIWYG than what's there now. It would include properly formatted admonitions with graphics, coloration to match the HTML build, etc. This is just a mini-news bulletin, not a call for a new toolchain. However, since the tool is available and may provide functionality for new contributors, it will probably be addressed in the Documentation Guide. -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

3 4

Red Hat Magazine, issue 7
by Paul W. Frields 23 May '05

23 May '05

Fellow scribes and scribblers, The illustrious editor-in-chief, Tammy Fox, is apparently too modest to announce it here, but Red Hat Magazine #7 is out! RHM7 (that's what the new teaser poster calls it -- look for it in your neighborhood movie theater) has the following Fedora-related articles: * Installing Fedora Core on the Mac mini, by Colin Charles * FUDCon 2: Coming to a LinuxTag near you * Fedora Project Status Report, by Greg DeKoenigsberg Of course, there's also the usual amount of up-to-the-minute news, excellent tutorial articles on VNC and MySQL, a cool bit on availability and a great feature on open source licensing that you (or your boss) might enjoy. I really look forward to this online magazine every month, and I'm so glad to see the new method of online publishing has really taken off for RHM. If you want to keep on top of new issue releases, you can subscribe to the RSS 2.0 feed here: http://www.redhat.com/magazine/rss20.xml Tammy certainly doesn't need me to do PR for the magazine; I just wanted to make sure everyone knew the new issue was out. The new issue will probably be out right after the FC4 release, so hopefully we can submit a small blurb about the Installation Guide and other FDP happenings in time for the Fedora Project Status Report in RHM8. -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

4 5

fdp css negates docbook attributes
by Thomas Jones 18 May '05

18 May '05

Has anyone here noticed that the css declarations removes the capabilities of various docbook elements? For instance, I have some data that I have put into a table. I followed all semantics of the CALS table attributes that docbook utilizes. Yet, I am unable to successfully alter the table attributes and their appropriate values to achieve the desired outcome --- because of html attribute inclusion by css. i.e. <table id="entities" frame="all"><title>Demonstration Entities and Relationships</title> <tgroup cols="3" align="left" colsep="0" rowsep="0"> <thead> ... Now this should result in the following: A framed table with three columns, all aligned to the left, and all rows and columns NOT seperated. But instead I get a framed table with a header background color of #a9a9a9, a body background color of #dcdcdc, all aligned to the left, and all rows and columns ARE seperated. To do this, i should have declared so using the bgcolor and border attributes. This breaks the element. Thomas

4 5

After wading through Bugzilla...
by David A. Lane, KG4GIY 17 May '05

17 May '05

Good evening all, My name is David Lane and among other things, I have been working with Red Hat since version 3 and I am currently working with Fedora Core 2 and 3 in different applications (such as Nessus for network testing). Anyway, looking around in Bugzilla, which I have not really been in since RH 8 when I had problems with the kernel on a laptop, has left me a little confused. I will probably be able to figure it out once I look at it again, but based on what I was seeing, it looks like there is a request for some over the wire (network) installation instructions (which have not been written) as part of a general installation guide - which also seems to be needed, a review of the samba-ldap-tutorial (#129739) and someone wanted an HCL update (along with a few other already written items). Am I reading this right? I have to get CVS up and running and grab the latest snap shot as well. Anyway, with a little luck, I think I might be able to find a niche where I can add to the overall whole. Personally, I am working on IPSec on the side, but I haven't started tinkering with it on the FC side yet... DAVID Oh, and I have also been interested in updating a very old HOWTO on AX.25 (the "ham" howto). But I need to pick up a TNC first. David A. Lane, KG4GIY EC/RO Prince William County ARES®/RACES +1.703.361.3042 http://www.qsl.net/pwcares/

2 1

Self-Introduction
by Neil Horman 17 May '05

17 May '05

Hey all, My self introduction: Name: Neil Horman Location: Raleigh, NC, USA. Profession: Software Engineer Company: Red Hat Goals: I'm planning on packaging utilities that are currently rather lacking in documentation (specifically git, cogito, etc). My current goal is to provide documentation as I build/release the pacakaged utilities. No good tool is complete without docs, right? I'd offer to help out with proofreading other documentation, but I really don't think anyone wants me doing that :) Historical Qualifications: I've been contributing to the Linux kernel and several open source projects (cscope, sctp, nfs, etc) for a year or so now, and publically active on thier requisite mailing lists for a few years. I've not had alot of docs experience, but I figure I'm going to try to build that up as I push more packages out to extras in the future. GPG key: pub 1024D/92A74FA1 2003-08-28 Neil Horman (my gmail address) <nhorman(a)gmail.com> Key fingerprint = 00BE 52A6 EB8E 979F 117E 101D 33E6 C4A1 92A7 4FA1 uid Neil Horman <nhorman(a)redhat.com> sub 2048g/C6D2F3B3 2003-08-28 Regards Neil -- /*************************************************** *Neil Horman *Software Engineer *Red Hat, Inc. *nhorman(a)redhat.com *gpg keyid: 1024D / 0x92A74FA1 *http://pgp.mit.edu ***************************************************/

1 0

Callout style + error
by Thomas Jones 17 May '05

17 May '05

I've attempted to determine some information about the callout images used in fedora's documentation --- to no avail. So I bow to the mercy of the mailinglist and ask for help. What is the standardized styling and location of the callout images? I have built custom callouts for current development of my xml sources; but didn't want to stray from standard practice. Also I came across a peculiar problem declaring the xsl parameter using xmlto. For some reason due to the java implemented processor, I am getting a ColumnWidth error. The only alteration performed was to include an extension stylesheet for the declaration of a new image path. :-( Admittedly, I have never used xmlto and prefer xsltproc. However it might be a moot point if the standard path is acceptable. Thanks, Thomas

5 12

CVS vendor and release tags
by Paul W. Frields 16 May '05

16 May '05

On Mon, 2005-05-16 at 00:04 -0700, tuxxer wrote: > OK, did some preliminary commands and they seem to work (they all > failed, actually, but I was querying modules that *shouldn't* exist > (yet), etc. so I got results that I more or less expected). So my n00b > question is this: > > How do I do my initial import of the hardening guide? > > I've read the CVSUsage WiKi, and (what I thought were) pertinent > sections of the Documentation Guide, as well as the CVS general > documentation. I haven't been able to glean a command line that works. > Help? I'm taking this to the list since it involves a general policy and procedural concern, which is CVS tags. In the past, Karsten and Tammy imported my sources, since there was no One True CVS access. In general, the command is: cvs import <repodir> <vendor-tag> <release-tag>... What are the vendor and release tags that people should be using to import? The answers should probably come from a consensus of three individuals -- Karsten (has done lots of importing before IIRC), Tommy (FDP CVS maintainer), and Tammy (resident CVS goddess). We should probably figure out how to do this rationally to allow for branching by Core release (viz. usb-hotplug tutorial). I don't know how these tags affect the structure of the repository, so I don't have any substantial ideas to offer. As long as the tags don't make it awkward for the project to expand to cover things outside Core (such as Extras), nor to handle translations, nor to branch, it's just a matter of these folk putting their heads together, with help from other list members. -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

4 9

.cvsignore files
by Paul W. Frields 16 May '05

16 May '05

I saw a .cvsignore pop up in the documentation-guide CVS this afternoon which ignores the HTML build directory. Personally, I like having the HTML build directory *not* ignored; it's a good reminder for me to check the build before I do a commit. Since, like all good CVS commandos in training, I do a lot of "cvs up," it reminds me to build often. If folks want to use this feature locally, by all means, do so! Simply make sure your local .cvsignore has an extra line that just reads ".cvsignore" so you don't end up getting a new and just as annoying CVS message. :-) In any case, there's probably no overriding reason to set a policy on this issue; the document owners should dictate what's done in their particular sandboxes. As the guy who's apparently going to spend the most time herding the Documentation Guide in the coming months, I will probably remove documentation-guide/.cvsignore at some point unless there are strenuous objections. -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

3 6

Taking screenshots
by Tommy Reynolds 16 May '05

16 May '05

I've noted that some screen shots include the window decorations, others do not. The "Documentation Guide" does not address it. Personally, I vote for no borders. What is the list's pleasure?

4 3

including small bits of XML as entities
by Karsten Wade 13 May '05

13 May '05

Paul was asking me this morning ... "I am going to ask quaid if he can figure out a way to get that XML chunk included without the surrounding <chapter>, so it can be included also as a <section> somewhere else, while allowing easy editing in Emacs" This was in reference to the common file cvs-en.xml in the /cvs/docs/common module. You can put _anything_ that is valid XML in a file and call it as an entity. Wherever you call the entity, it must be valid or an error will occur. For example, you can have a stand alone <section> in a single file. If you define the part within the fedora-entities-en.xml file or within your parent XML file as, for example: <!ENTITY FOO SYSTEM "./foo.xml"> Then you can call it with &FOO; anywhere that the <section> is otherwise legal. Similarly, the contents could be: <para> This is a common thing I put all over the place so have made an entity for it. </para> You can put just that XML in a file and call it as an entity. It must be legal wherever you call it. So, this would be a legal usage: <para> Here is something to read: </para> &FOO; <para> Got that? </para> This would _not_ be legal and would generate errors upon building or using Emacs to validate the file with C-c C-v: <para> Here is something to read: &FOO; Got that? </para> - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

3 2

Updated Hardening guide.
by tuxxer 13 May '05

13 May '05

Beat me up again guys and gals. ;-) http://members.cox.net/tuxxer http://members.cox.net/tuxxer/fedora-hardening-guide-whole-en.xml XML also posted to bug #129957. -Charlie -- -tuxxer gpg: 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1

6 15

Dearth of activity recorded on the schedule page.
by Tommy Reynolds 12 May '05

12 May '05

Hey, folks! Don't forget the Fedora Docs Schedule wiki at http://fedoraproject.org/wiki/DocsProject/FedoraDocsSchedule This is the place to keep progress notes, your tickler file, or any measurable activity for the project. Use it instead of all the yellow stickies on your desk: less clutter for you, visibility for the rest of the project. And remember its greatest benefit of all: "Well, it beats status reports." -- Me Cheers!

1 0

Self Introduction: Binh Nguyen
by Binh Nguyen 12 May '05

12 May '05

Full legal name: Dai Thai Binh Nguyen (everyone calls me 'Binh') City, Country: Melbourne, Australia Profession or Student status: Mostly student but also do some contract work (computer related, not necessarily Linux) Company or School: University of Melbourne, CAE (Computer Science/Physics/History and Philosopy of Science/Business). Your goals in the Fedora Project: What do you want to write about? Fork my Linux Dictionary/Computer Dictionary for suitability to Fedora Project. What other documentation do you want to see published? Not sure yet.... I have some things in the works but they're fairly general.... Do you want to edit for grammar/writing and/or technical accuracy? Depends on the size of the document. If its reasonable, ie. smaller than 10 pages than I'll be more than happy to do a review/edit for grammer/technical details. Anything else special? Not at this moment in time. Historical qualifications: What other projects or writing have you worked on in the past? TLDP (Linux Documentation Project), (Author "Linux Dictionary" and "Linux Filesystem Hierarchy") TSF (The Shuttleworth Foundation), Computer Dictionary Project (Author/Project Administrator/Development Lead/Commiter "Computer Dictionary") Published technical/commentary articles at linmagau.org, desktoplinux.com, newsforge.com, linuxtoday.com, linux.org, pclinuxonline.com, tuxreports.com, etc.... Sourceforge, SpeechSuite (Project Administrator/Development Lead "uses speech technology to allow interfacing with the Linux CLI; currently in second stage of evolution, see homepage for details) What level and type of computer skills do you have? Fairly competant, can write/program/dabble in hardware, etc.... What other skills do you have that might be applicable? User interface design, other so-called soft skills (people skills), programming, etc. Experience in: - User Interface Design - Programming (C/C++/Java/Prolog/Haskell/x86Assembly/PHP/HTML/XML/BASH/SQL/etc....) - Recently been playing around with speech and home control technology (see homepage) What makes you an excellent match for the project? I get a kick out of producing high quality pieces of technical work. :) Binh. (Homepage, http://www.geocities.com/linuxfilesystem/) [binh@nx5000 ~]$ gpg --fingerprint 50618576 pub 1024D/50618576 2005-05-12 Binh Nguyen (Fedora) <linuxfilesystem(a)yahoo.com.au> Key fingerprint = 9C9D D2BE 0A5C 248B 7085 A6C0 F2BE 264B 5061 8576 sub 1024g/C9CCADC5 2005-05-12

2 1

Self-Introduction: Max Kanat-Alexander
by Max Kanat-Alexander 11 May '05

11 May '05

/me thinks "Hrm... I've been writing the FAQ since the day FC1 was released. :-) Maybe I should do one of those self-introduction things on some list, someday..." :-D I also figured that maybe it was time to sign up for the fedora-docs- list. :-) So, happy coincidence, both of these thoughts happened simultaneously. Personal Details ---------------- Full legal name: Maxwell Kanat-Alexander City, Country: San Jose, CA Profession: Founder & Computer Guy Company: Everything Solved I'm also the Release Manager of Bugzilla, as well as being one of its primary contributors. Fedora-Docs and Me ------------------ + Your goals in the Fedora Project: Be nice. Help out. Have fun. :-) + What do you want to write about? Trogdor. And love. However, failing that, I'll write the uFAQ. :-) And maybe somebody could coax me into writing some other stuff, some day... who knows. :-) + What other documentation do you want to see published? Well, I'd like to expand my Fedora Basics FAQ a bit, here and there. :-) + Do you want to edit for grammar/writing and/or technical accuracy? Well, I certainly *could*... it might take waving a dead fish in my face, though. :-) No, but seriously -- if it's ever like, down to the last minute, and you desperately need an editor, I'll do it. I'm quite good at it. :-) + Anything else special? I'm mostly just here to provide witty comments and insight if I have something to say. And maybe I'll get caught up in something interesting and contribute a bit. :-) Historical Qualifications ------------------------- + What other projects or writing have you worked on in the past? Well, http://www.fedorafaq.org/ for one. :-) I also wrote a lot of the Kerio (where I used to work) Knowledge Base, and some Bugzilla documentation here and there. Oh, and I wrote a 50-page training manual for Kerio, too. And finally (in my never-ending string of paragraphs with obviously creative and unique transitions like "and" and "also") I'm an excellent songwriter. I'm not sure how relevant that is, though. :-) Unless you want a Fedora Theme Song. + What level and type of computer skills do you have? Amazing. + What other skills do you have that might be applicable? User interface design, other so-called soft skills (people skills), programming, etc. I am really, really good at talking to people. I'm also really good at explaining how things work. I'm also particularly good at taking very busted, messy processes or code and making them shine in the morning light. + What makes you an excellent match for the project? Me and the project have been going steady for about two years, now. I think we might get engaged. GPG KEYID and fingerprint: [maxka@localhost ~]$ gpg --fingerprint A1093CAE pub 1024D/A1093CAE 2000-05-23 Max Kanat-Alexander <mkanat(a)bugzilla.org> Key fingerprint = E119 9240 601C 389A 9FF0 3DE6 68BD 83FD A109 3CAE uid Maxwell Kanat-Alexander (Primary email starting in Sept. 2003) <maxka(a)myrealbox.com> uid Max Kanat-Alexander <max_list(a)fedorafaq.org> sub 1024g/8D25F5F0 2000-05-23 Note that that doesn't include any of my actual personal email addresses. :-) Just use this one. :-) -Max -- http://www.everythingsolved.com/ Fedora is definitely part of the "everything" in Everything Solved.

3 3

New CVS Layout Tips And Techniques
by Tommy Reynolds 10 May '05

10 May '05

Greetings, Folks! To make life simpler, we have reorganized the CVS setup for Fedora Docs. Previously, there was one big module called "fedora-docs". You checked that out of CVS and you had the all the documents from the entire project. While you could check out just the part you were interested in, doing so was clumsy. Adding a new document was equally awkward. With the CVS changes now in place, each document forms its own CVS module and can be checked out individually. Everything that used to be in the "fedora-docs/" directory is now a top-level module. The "fedora-docs/" directory is no more; it is an ex-directory; it is pining for the fjords ;-) Sorry. 1) To see which modules exist (assuming that your $CVSROOT environment variable is properly set): $ cvs co -c 2) How do you access an existing document? First, create a working directory. A "fedora-docs/" holding directory isn't created automatically as before, so make: a) yourself a playpen; and then b) get the overhead doc modules; and then c) get or create the document you want. Here is how it goes together: $ mkdir my-docs-dir $ cd my-docs-dir $ cvs co docs-setup $ cvs co example-tutorial Note that the "docs-setup" actually gets four modules for you: "common", "css", "stylesheet-images", and "xsl". You need these for any document you view or create. Since each document you get from CVS can share a single "common/", "css/", "stylesheet-images/" and "xsl/" directory, you only need to do this once regardless of how many documents you work on simultaneously. 3) How do I begin a new document? Much the same was as you do an existing document. You still need the "docs-setup" checkout, described in the previous section. Create a new directory for your new document and away you go. A good technique is to use an existing document as a model: $ mkdir my-new-document-sandbox $ cd my-new-document-sandbox $ cvs co docs-setup $ cvs co -d my-doc example-tutorial $ rm -rf my-doc/CVS Be sure to remove the CVS directory from your new document's working area ("my-doc/CVS" in our example) because your document has not been added to the Fedora CVS system yet. 4) How do I get my document into the Fedora CVS system? Sign up for CVS access! If you have followed the instructions above, you can add your document to the Fedora CVS easily. Rename your working directory, just to be safe, import your document into CVS, and the check out the "official" verion of your document. NOTE: take care that you do not try to import a directory named "CVS"! Your new document should not have *any* CVS directories before your import is finished. Continuing our previous example: $ mv my-doc my-doc-orig $ cd my-doc-orig $ cvs import my-doc <my-name> "initial" $ cd .. $ cvs co my-doc Notice that we renamed the working copy to "my-doc-orig", and then imported that using the real name of "my-doc": this is the actual module name for your document. Compare its contents with that of your original "my-doc-orig" directory to ensure its correctness. Feel free to delete your "my-doc-orig" directory whenever you wish or keep it forever - your choice. The Fedora CVS administrator will add an entry into the official modules listing for you, so you should be see your new document in the "cvs co -c" listing very soon. 5) Single-Point Updates A document setup consists of two CVS entities: the "docs-setup" group and the specific document tree. For example, checking out the example tutorial: $ mkdir a-new-world $ cd a-new-world $ cvs co docs-setup $ cvs co example-tutorial Now, look at the working directory: $ ls -CF common/ css/ example-tutorial/ stylesheet-images/ xsl/ That makes 5 separate CVS objects to keep updated. The directories created by the docs-setup form the infrastructure used by your document. If you want to keep everything updated, you could do this: $ cvs update * in the "a-new-world/" top-level directory. You can also update your working document from within its directory, as usual: $ cd example-tutorial $ cvs update 6) I already have documents checked out using the old setup. Now what? Congratulations on being a current FDP activist! You have two choices, depending on your confidence: A) Keep what you have. Edit each "CVS/Repository" file in your local hierarchy to remove the "fedora-docs/" prefix from the pathname you find there. For example: $ cd example-tutorial $ cat CVS/Repository fedora-docs/example-tutorial $ vi CVS/Repository $ cat CVS/Repository example-tutorial B) Punt and do a fresh checkout. Shhh, we won't tell! Please enjoy your stay here in Fedora Docs CVS land.

1 0

release notes beats
by Karsten Wade 10 May '05

10 May '05

We have an important job in producing the release notes for Fedora Core. My idea for doing this is to breakdown the relnotes into journalistic beats. In journalism, a beat is a certain area that a writer is in charge of writing about. For example, the local City Council would be a beat. The writer in charge of that beat would attend the Council meetings, meet with the members of the Council, research the issues, and write about the Council with all the background necessary. This writer becomes associated with the City Council beat. Doing this with the release notes makes it possible for a volunteer group to manage a complex task. If we think of the relnotes like a newspaper, then each beat reporter is only responsible for writing one or two columns to get the issue out the door. That is a much easier task than writing the entire newspaper yourself. Here are the categories that I have come up with so far. * Kernel * Desktop * Printing * Server Configuration Tools * File Systems * File Servers * Web Servers * GCC/Development Tools * Security * Java * System Daemons (cron, etc.) * Sound and Video * X Window System (xorg) * Status of all Packages What is missing or should be changed about these? Are these attractive beats that will give you the chance to write about what you are interested in? Is there a developer team you want to be closely involved with? Is there a beat that connects with the work that you currently do or want to do? Should some of these be handled by a beat team? This is idea is fairly simple, which is the key to its success. If you are interested in covering one or more beats, please choose your favorites and let's get this started. For more of an overview of the process, including ideas for engaging and interacting with developers, this Wiki page is the current work-in- progress: http://www.fedoraproject.org/wiki/DocsProject/ReleaseNotes/Process - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

2 1

Re: Are Fedora docs readable?
by Karsten Wade 10 May '05

10 May '05

On Tue, 2005-05-10 at 23:00 +0100, Timothy Murphy wrote: > On Tue 10 May 2005 12:47, Karsten Wade wrote: > > > I do not see the word "document" in the title. Aside from that, your > > argument is specious. This is open source software we are using, the > > ultimate documentation is _always_ the source code. Your inability to > > understand it does not make it any less valid. Sorry if that is harsh, > > but it's a common truth. > > It's not particularly harsh, just silly. > If someone googles for "Fedora tutorial" or whatever, > and is directed to an unreadable article, > with no instructions as to how to make it readable, > they will conclude that Fedora is for pointy-heads. When you come up with the secret formula for controlling what Google returns, let us know. Otherwise, we can't be responsible for Google finding an informal, alpha document for a version of Fedora Core we no longer document. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

2 1

Self-Introduction: Andrew Jones
by Andrew Jones 10 May '05

10 May '05

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Full name: Andrew Jones City, County: Bath, Somerset, UK Profession: Student School: The University Of Bath Goals: I'd like to write documents targeted at new users. I've been using linux exclusively for a while, but I can still remember what it was like to be a new at it. I'm happy to edit for grammar/spelling and technical accuracy. Qualifications: No paper qualifications. My knowledge has come from installing linux to use as a desktop, and for a few servers for home networks. I know a bit about the obvious things that most servers need (dns, dhcp, samba and so on). I'm taking a networking course at university so understand the fundamentals well. I program C well, and Python not so well, but would be interested in developing these skills in parallel with (perhaps even because of) the doc project. Cheers, Andrew GPGKey: pub 1024D/385622CD 2005-05-09 [expires: 2006-05-09] Key fingerprint = 08AE 82DB 3029 E1DA 7066 1265 220C AEB1 3856 22CD -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.1 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org iD8DBQFCgRAwIgyusThWIs0RAjUDAJ4k308Y73n5yIw/k0hu4aetLg5/uwCdFTMf WXw2AEDXKXCYSnzrM5j70yI= =tD8c -----END PGP SIGNATURE-----

2 1

moving CVS stuff around a bit
by Karsten Wade 10 May '05

10 May '05

Right now we're moving all of the documents in the fedora-docs module into their own modules in /cvs/docs. Until then, don't do any check-ins. We'll send out directions on using the new modules shortly. -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

1 0

Are Fedora docs readable?
by Timothy Murphy 10 May '05

10 May '05

I was looking for a document that would explain how Linux/Fedora decides what driver to use with a given USB device, and google directed me to usb-hotplug-tutorial. Unfortunately this appeared to be in XML, and required a DTD which I could not find. Are these documents currently unreadable? If not, perhaps a link to an explanation of how to process them might be in order. -- Timothy Murphy e-mail (<80k only): tim /at/ birdsnest.maths.tcd.ie tel: +353-86-2336090, +353-1-2842366 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland

8 13

Self-Introduction: Gavin Henry
by Gavin Henry 10 May '05

10 May '05

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Full legal name: Gavin Clive Henry City, Country: Aberdeen, Scotland Profession or Student status: Managing Director Company or School: Suretec Systems Ltd. Your goals in the Fedora Project: What do you want to write about? OpenLDAP, Squid, Amanda, Samba, Postgresql, Exim, SSH and anything network/server/security related. What other documentation do you want to see published? Comprehensive User Guide and documentation somewhat simliar to the versions of Red Hat Enterprise Linux Do you want to edit for grammar/writing and/or technical accuracy? Yes. Anything else special? Help create a better toolchain for PDF generation and help gather new writers/editors. Also, help maintain a successful documentation project. Historical qualifications: What other projects or writing have you worked on in the past? I help maintain: [http://www.amanda.org/docs/using.html The Official Amanda Guide] I also have authored serveral documents for my company, which will be released to the Fedora Docs Project in the near future. What level and type of computer skills do you have? If I may say so, Expert. What other skills do you have that might be applicable? User interface design, other so-called soft skills (people skills), programming, etc. People skills, friendly personallity and programming experience, as well as expert Linux Admin skills. What makes you an excellent match for the project? Read above ;-) GPG KEYID and fingerprint: [ghenry@suretec ~]$ gpg --fingerprint DB73BEA8 pub 1024D/DB73BEA8 2003-09-28 Gavin Henry (Suretec Systems) <ghenry(a)suretecsystems.com> Key fingerprint = 0391 864C 2CBB 4756 D817 CE40 796B 1E87 DB73 BEA8 sub 2048g/765253B8 2003-09-28 - -- Kind Regards, Gavin Henry. Managing Director. T +44 (0) 1224 279484 M +44 (0) 7930 323266 F +44 (0) 1224 742001 E ghenry(a)suretecsystems.com Open Source. Open Solutions(tm). http://www.suretecsystems.com/ -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.6 (GNU/Linux) iD8DBQFCgLSweWseh9tzvqgRAsvXAJ9SfssvsRxzbnF9DPxdXBZUqSH0aQCeNgml Ot5nJO0vUged2Icmt384rYM= =jmyO -----END PGP SIGNATURE-----

2 3

Minutes from FDSCo (03-May-2005)
by Karsten Wade 09 May '05

09 May '05

## For those wondering what is happening in the Documentation Project: Fedora Documentation Steering Committee (FDSCo) 03-MAY-2005 #fedora-docs on irc.freenode.net Attendees: ========== Karsten Wade (chair) Tommy Reynolds Tammy Fox Gavin Henry Paul Frields Stuart Ellis New Actions: ============ FDSCo: Find ways to get fame to documentors. Name up in lights. Etc. FDSCo: You can post a link to your own self-intro or similar on your Wiki page. FDSCo: Take the divided list of writers who have volunteered and contact them directly to see what help they need, or what their status and interest is. Gavin: To make a Wiki Contributors page that incorporates the Writers and Editors pages somehow, linking to Self-Intros. This is part of the "find the interested writers" sub-project. Gavin: Hunt fedoraforum.org for doc ideas and writers. Gavin: To look into getting a FDSCo interview on lugradio.org. Paul/Karsten: FDL for the new style chapter Karsten: Assign task of making docs use common files in ./ instead of ../, in order to work for separate modules per document. Karsten: Deliver minutes that are better organized, using the FESCO minutes as an example. Will start posting to fedora-announce as well as fedora-docs-list. Karsten: Look into reordering CVS to make all documents in fedora-docs module into separate modules. Tommy: Convert tasks into a schedule, split out goals, borrowing from Extras template. Tammy: How to create a new CVS module, for the Doc Guide. Tammy: Look into ViewCVS. One objective is to get regular reports of activity on documentation, in order to help define abandoned docs. Tammy: Looking into sponsorship of Doc Days and similar incentives for community participation. Action Status: ============== * New writers will find this page very useful in getting started: http://fedoraproject.org/wiki/DocsProject/NewWriters * Details on gaining CVS access are available at: http://fedoraproject.org/wiki/DocsProject/CvsUsage * Stuart has made signficant progress on tracking the status of all documents ever proposed or in the works, pulling together information from disparate locations. http://fedoraproject.org/wiki/DocsProject/EditorAssignments * Paul and Karsten have the first iteration of the style guidelines put into the Doc Guide. These are required reading for writers and editors to be able to work together. http://fedora.redhat.com/participate/documentation-guide/ch-style.html * Karsten announced the style changes and noted they are required reading for writers and editors. * CVS is available at /cvs/docs for all documentation projects. Discussion Results: =================== IDEA: A Docs Day, contest/competition with booty/prizes, for example, Bug Bounty. NOTE: CVS: Separate module for all docs, makes it easier to check out. NOTE: Wiki is acting as a work-in-progress area to make process and info available immediately. Eventually, all of this will be in the Doc Guide. NOTE: If ViewCVS doesn't provide the reporting we need to track documentation activity, we can look into scraping fedora-docs-commits into a Wiki. Objective is to use existing tools to capture document status instead of having another Wiki page for everyone to keep updated. NOTE: A layout/outline using blank XML pages is considered enough to get into CVS with. NOTE: Snot is considered off-topic. NOTE: It's nice to have a list of closed and accomplished tasks. -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

4 14

research on using the GFDL
by Karsten Wade 06 May '05

06 May '05

Since we incorporated some text from the GNOME Documentation Style Guide (GDSG), we need to update our Doc Guide to attribute the included content covered under the GFDL. Then we need to decide if we're forking. I think we are. We will have to manually include patches from GDSG. The diff between the two guides will be too great, and will go over time. However, we need to capture immediately the bug fixes we made so we can get them upstream, before they get lost and our reasoning gets stale. Paul, can you dig out from SVN what you did previously? We'll add that to the fixes I made and you made in cvs.fedora and split up the list to file bug reports. Now, on to the fun stuff ... Today I read the GFDL again, read some opinions from debian-legal, and did some thinking. Here is what I have so far. http://www.gnu.org/licenses/fdl.txt ## We need to take an action to comply with this: B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. ## We need to create/modify History, with that title :/ I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. ## After some digging, here is one of those canonical pages: http://developer.gnome.org/documents/style-guide/titlepage.html ## The whole thing with "Exactly Named Pages" is a little strange. The ## GDSG doesn't have a link from the ToC on index.html to ## titlepage.html. ## The following action is to make sure there is a page, on or linked ## from the "History" page, that tells how to get the source for the ## document. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. ## We need to redo the organization a bit, I think we all like the way ## GNOME doc prefaces are laid out. We can start by creating a History ## etc. to fulfill licensing agreements. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. ## Beginning to wonder if we need an appendix to cover some of this ## stuff ... ## Here is an important part that tells us exactly what we need to do in ## combining the documents, which is arguably what we did: 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements". #################### One problem I am hearing about occurs if we include the "Acknowledgements" or "Dedication" section, we may greatly reduce the freedom of our document. In this matter I defer to the debian-legal list for all the reasoning. Here is a page that appears to cover all the details: http://people.debian.org/~srivasta/Position_Statement.html Because the GDSG doesn't include any Invariants or other immutable content, we are fully free to use it. Similarly, our GFDL is nicely fully free. Anyway, I don't want to seek legal advice unless we can't find a clear precedent of how to act. It's seeming clear, so far. cheers - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

4 12

All writers and potential writers list
by Gavin Henry 04 May '05

04 May '05

4 3

[RFC] dumping the CED in favor of local variables
by Karsten Wade 04 May '05

04 May '05

I'd like to recommend we dump the usage of CED files in favor of the local variables designation. The CED file is a pre-compiled DTD subset. http://fedora.redhat.com/participate/documentation-guide/s1-emacs-cedfile.h… The only noticeable change that matters is that indenting is different by two characters overall. It's really no big thing to reindent entire files, or sections of them to avoid <screen> blocks. The CED files technically need to be recompiled with the introduction of each new tag. They are a hassle to load everytime you load the document. The local variables will load the parent file in the buffer, which is convenient, and does all this automatically when you open the file. You put one of these at the bottom of each XML file:  The small pain of converting our docs will be more than made up for in the not-so-long run. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

4 6

Submitted Document Bugid: 156771
by Thomas Jones 04 May '05

04 May '05

Hello all, As per a recent conversation, I have generated a patch for the general entity file --- fedora-entities-en.xml. https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=156771 There were a great many changes that I have made. Not all may be accepted into CVS; but I believe that these changes provide good value to the project. As you review the changes, please keep the following "open" issues in mind: - this file is incorrectly identified as xml. When in fact, it does not contain any XML markup at all. Just a thought. In keeping with standardization, it should be something like en.fedora.dbgenent.ent. But, thats just personal preference. ;) - if the "bluecurve" entity is accepted; does the <interfacedefinition/> element suffice as the parent node with its expected context? - if the "rpm" entity is accepted; what is its legal status? registered or trademark? - i neglected to utilize the common ISO entity declarations for readability. New authors find it difficult to read if utilized; yet translators probably need the ISO declarations. I prefer ISO --- but then again i am weird. ;) Hopefully, this will help. Thomas

2 2

new Style chapter, required homework
by Karsten Wade 03 May '05

03 May '05

We finally got Paul's excellent work included in the Doc Guide. This style guideline is largely derived from the GNOME Documentation Style Guide. We have customized it, fixed some (!) errors, and generally stood on the shoulders of giants. Writers and especially editors should be thoroughly knowledgeable of this: http://fedora.redhat.com/participate/documentation-guide/ch-style.html And should be familiar with these or the concepts embodied there: The Elements of Style, by William Strunk. Online version: http://bartleby.com/141/ The Chicago Manual of Style, by the University of Chicago Press. Online version: http://www.chicagomanualofstyle.org/ Paradigm Online Writing Assistant, maintained by Chuck Guilford, Ph.D. Online only: http://www.powa.org/ We'll work on following these guidelines throughout Fedora documentation. We will all continue to make the same mistakes, no matter how experienced we are. This is why we edit each others work and have style guidelines to remind us of what and why. cheers - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/

2 2

fedora-docs-commits authorship
by Paul W. Frields 03 May '05

03 May '05

It looks like the commits list is not catching authorship correctly. I noted that Elliot's first test (README 1.3 -> 1.4) worked properly. All commits after that seem to be authored by the list: http://www.redhat.com/archives/fedora-docs-commits/2005-May/author.html Can we get this fixed? I don't know who the responsible party is, otherwise I'd mail directly. (I thought I caught something on IRC #fedora-docs that implied Elliot doesn't take care of this part.) -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

2 3

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

docs May 2005