docs June 2005

docs@lists.fedoraproject.org

33 participants
57 discussions

tidy-bowl - BETA invitation!
by Paul W. Frields 10 Jul '05

10 Jul '05

Greetings FDPers, Tommy and I have been collaborating on a method to mitigate our problems with multiple editors. When FDP started, we envisioned a beautiful, pristine world in which everyone used Emacs+psgml -- pipe down, Tommy ;-D -- and collaborating writers and editors would not end up reformatting each other's work, since they were using the same tools. However, that expectation has proved somewhat unreasonable, especially in light of (1) our goal to lower barriers for entry as far as possible, and (2) the proliferation of XML editors out there. As a result, the FDP canon will, in all likelihood, no longer require people to use specific tools, although a preference for Emacs+PSGML is likely to linger, since the majority of the editors are using those tools. An XML normalization engine (xmlformat) will reformat docs when they are imported or committed to CVS. It uses a configuration file which should not complicate life for writers or editors using most tools of which we're aware. Because the normalization does not change the actual copy of the file on your disk, you don't have to worry about how the committed version might have different whitespace, margins, blocking, etc. from your copy on disk. You simply keep editing as usual. Any person checking out a file from CVS will get the normalized version, which they can feel free to *reformat* locally. Any such changes will be "stripped" when commits are made. Only the content matters. CAVEAT: Once you make a change to a .xml document where your local copy is NOT normalized, when you use the "cvs diff" command, the diff will be very long because of the normalization differences. Sorry, folks, that part's out of our hands; it was the price we paid to allow more tools out there, and it seems worth it. The diff that actually ends up going to the fedora-docs-commits list from the CVS server *will* be sane. If you must have a sane local diff, you can run "cvs up -C <file>" to replace your non-normalized file with the normalized version from the repository. If you have uncommitted work in the file, commit it before you run that command, or it will be lost. The only drawback is that your editor may want to reformat the file again when you next load it. This will not affect CVS. So now, THE INVITATION: For now, the only module that is normalized is the xml-normalize/ module. Please feel free to add files there and observe the results... i.e. beat on the script. If something breaks, please report problems to the list, Tommy, or me. Please check the log for a file before you diddle with it, so as not to inconvenience another tester. Thanks and have fun! -- 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 6

Back from my hiatus
by Thomas Jones 01 Jul '05

01 Jul '05

Hello all, Sorry to the fedora project for the inconvenience of my quick retreat. Real-world issues needed my attention. It seems that the issues are abated and things are returning to a normal status(whatever that may be). However, I did find the time to devote to researching and begin writing meaningful parts of the "Securing Filesystems" documentation. It is coming together rather nicely if I do say so myself ---- grammar not included. ;) Again, I am sorry. I will be leaving the week of the 11th to go to Chicago for some training but will return the week thereafter. Figured I'd give a heads-up this time. ;) Cheers, Thomas

1 0

Self-Introduction: Tatsuo Sekine
by SEKINE Tatsuo 30 Jun '05

30 Jun '05

Hi all, this is my self introduction: Full legal name: Tatsuo Sekine (In our culture, surname is coming first. So, I normally write my name "SEKINE Tatsuo", however, my name is "Tatsuo Sekine" in English :-P) City, Country: Sydney, Australia (temporary: I'm living in Sydney until this November) /Yokohama, Japan Profession or Student status: Student (temporary: I'm studying English now) /IT engineer/IT writer Company or School: a private English language school /System Design & Research Institute Co., Ltd. Your goals in the Fedora Project: o What do you want to write about? First of all, my first language is Japanese, so I'd like to translate documents. If I can feel confidence about my English, I'd like to write about yum repository construction. o What other documentation do you want to see published? Now, I have no idea. o Do you want to edit for grammar/writing and/or technical accuracy? Yes. Technical accuracy is really important, though my grammar/writing is sometime terrible. Usually, I trace the document step by step when I am translating. At that time, I notice technical inaccuracy/ambiguity. Actually, I've reported some bugs as the result of translation. o Anything else special? I (and some other) am really interested in the translations. (So, I'll join fedora-trans-list later.) Historical qualifications: o What other projects or writing have you worked on in the past? I'm a member of Fedora JP project where we translate and publish a lots of document. I'm currently translating the RELEASE-NOTES. Moreover, I have committed RH/Fedora via the bugzilla(#89292,#126940 and so on). Apart from Fedora related project, I'm also a member of Linux JM project where we translate Linux man pages. In addition to that, the one of my job is technical writing, so I have written some books for Linux administration and shell scripting. Additionally, I was a member of Kondara Project which was also free distribution project. Unfortunately, that project have been discontinued for some reasons. o What level and type of computer skills do you have? Novice kernel hacking, expert RPM packaging and etc. For more detail, please see my profile on SF.net: http://sourceforge.net/people/viewprofile.php?user_id=4153 o What other skills do you have that might be applicable? User interface design, other so-called soft skills (people skills), programming, etc. I have not written programme for a long time, however, I hope that I can do it still now. o What makes you an excellent match for the project? I'm not sure. * GPG KEYID and fingerprint: $ gpg --fingerprint 24DBA1FC pub 1024D/24DBA1FC 2003-01-09 Key fingerprint = 18FE E474 7399 3E74 FCE4 F36E C26C 9AD7 24DB A1FC uid SEKINE Tatsuo <tsekine(a)sdri.co.jp> sub 1024g/70477FE4 2003-01-09

4 3

[ANN] docs-common/Makefile.common
by Tommy Reynolds 30 Jun '05

30 Jun '05

Ahoy, Fellow Dockers! To increase the maintainability of the document build process, the Steering Committee has decided to make a significant change to the Makefile's used to construct each document. A new file "docs-common/Makefile.common" has been created and _all_ of the default make(1) targets and rules have been moved to that file. Now, a document's local Makefile is very short and only needs to define some boilerplate macros, plus the all-important DOCNAME macro. Armed with this information, and including the "../docs-common/Makefile.common" file, you will be ready to generate HTML's, PDF's, tarballs, and however else it is decided to package our documents. To see this in action, update your "docs-common" directory and then look at the "Makefile" in the "example-tutorial" project. I hope this change will insulate the individual document files from future mangling as we add new capabilities. Technical note #1: Since all the make targets defined in "Makefile.common" use double-colon (::) definitions, adding any additional steps needed for an unusual document is easy. In your local "Makefile", add your own target, such as "${DOCNAME}/index.html::" followed by your own rules. For an example, again look at the example tutorial. Technical note #2: In the local "Makefile", the XMLFILE macro still references the main XML file for your document -- the file that contains the DOCTYPE declaration. If your document includes any external files, just list their names in the XMLEXTRAFILES macro so the dependencies will all work out. As always, if you have questions, feel free to submit them to this list and I'll explain or apologize as necessary ;-) Tommy

4 13

OpenOffice.org update
by Paul W. Frields 29 Jun '05

29 Jun '05

Re: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=158903 OpenOffice.org DocBook XML "save as" function now works as expected. Note that you need to have openoffice.org-javafilter package installed, else you will end up with an empty file saved, and/or an OO.o crash. Note also that if you try to open the saved .xml file, the import filtering is *not* working and you will lose all formatting information. You can simply save a native .odt (OpenDocument Text) format document, using that as your working copy until you are ready to export a copy for use in CVS. The only useful purpose I can see for using OO.o in this fashion is to make quick document sketches that use only <section>, <title>, and <para>. There is probably plenty of other DocBook stuff that is well-implemented, but I haven't tried to suss it all out, and don't have any plans to do so. If there's anyone out there with the wealth of knowledge it would take to get working XSLT (and DocBook styles) for some of the more esoteric DocBook used by FDP, particularly admonitions and <variablelist>s, have at it! I'm not even sure how that would work, but I imagine OO.o must have functions to allow users to point to extra XSLT stuff just as it does styles. The upshot is that rank beginners who are not friendly with Emacs, vi, or any other more UNIX-y tools now have a shot at drafting docs with minimal pain. The resulting DocBook XML will be uncluttered and readily understandable by the author. The editor can now proceed to introduce the author to additional DocBook-ism. -- 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 1

Saxon?
by Tim Waugh 29 Jun '05

29 Jun '05

What's all this about changing xmlto to use Saxon instead of xsltproc? How will that fix PDF output? Tim. */

3 9

Self-Introduction: Yoshinari Takaoka(a.k.a mumumu)
by Yoshinari Takaoka 29 Jun '05

29 Jun '05

hi, all. yesterday i joined #fedora-docs(irc.freenode.net) and talked with some FDSCo members, im grateful to them for leading me here. here's my self introduction. ---- Full legal name: Yoshinari Takaoka City, Country: Tokyo, Japan. Profession or Student status: Software Developer. Company or School: Japan Systems Enginnering Co.Ltd. Your goals in the Fedora Project: What do you want to write about? i am working on fedora JP project(http://fedora.jp), fedora users and enthualists group in japan and aims at improving japanese environment and resources. therefore, i want to translate documentations published by fedora documentation project into japanese, and increase japanese resources about fedora. What other documentation do you want to see published? i want to contribute japanese specific faq about fedora. of course, i know there are fedora unofficial faq( and its japanese translation). if i find questions which is not in it, i want to contribute to it, too. Do you want to edit for grammar/writing and/or technical accuracy? yes. especially technical accuracy, because it takes a long time for me to write documentations in english. Anything else special? i want to contribute maintainance of fedora extras packages which is useful to japanese, for example kinput2, skkinput and so on. unfortunately, i dont have skill to do so....only translation now. Historical qualifications: What other projects or writing have you worked on in the past? I helped translating technical interview published on slashdot.org into japanese and now translating fedora-installation-guide. What level and type of computer skills do you have? Programming skill: java(Expert), php(intermediate), and python(novice). Web application development skill : Expert. Linux server administration skill : intermediate. translating and writing technical document : maybe, intermediate. What makes you an excellent match for the project? maybe, experience of translation, and endless curiosity. :-) GPG KEYID and fingerprint: mumumu@mu-hoe-narinari:10:35 p.m:~ > gpg --fingerprint ------------------------------- pub 1024D/9C1F362D 2005-06-29 fingerprint = 2600 7C9B 0FFE 1EB7 C8F4 F80A 04E6 EAEA 9C1F 362D uid Yoshinari Takaoka (a.k.a mumumu@IRC) <mumumu(a)mumumu.org> sub 2048g/3B2DCC0C 2005-06-29 Best regards. -- Yoshinari Takaoka(mumumu@IRC) reversethis -> {gro} {tod} {umumum} {ta} {umumum}

3 2

Handling Multiple Document Versions in CVS ?
by Stuart Ellis 29 Jun '05

29 Jun '05

I've now got source files for a FC3 version of the Installation Guide, and so need to check this in alongside the FC4 version currently in CVS. AIUI we can either create subdirectories within the CVS modules for each version, or use tag/branch features of CVS. In case it makes a difference - each version is about 18 MB (due to graphics). -- Stuart Ellis stuart(a)elsn.org Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ GPG key ID: 7098ABEA GPG key fingerprint: 68B0 E291 FB19 C845 E60E 9569 292E E365 7098 ABEA

2 2

Additional writing guidelines
by Paul W. Frields 29 Jun '05

29 Jun '05

As a ramp-up to working on the DocGuide, I am catching up on some editing. As I do so, and at the risk of sounding pedantic or picky, I wanted to share some thoughts with the list. I've been dipping into a bunch of the languishing tutorials and only doing real work on one or two, so I'm not going to point out specific examples, especially since that might be construed as unfair criticism of a particular work. The fact that there is any material at all to edit is a BIG credit to the hard-working volunteer writers who provided it. I hope these thoughts might be helpful to some of the people who have come on board recently and are preparing ideas for future tutorials. Comments and discussion are welcome. You may wish to refer to and comment on: http://fedoraproject.org/wiki/DocsProject/DocumentationGuide 1. Organization: All tutorials and guides should have an introduction. All tutorials should follow the introduction content standards listed on the wiki. Remember that tutorials are *task-oriented*, and not meant to be lectures reduced to XML. Constantly ask yourself: "What are the objectives of this tutorial? What will the user BE ABLE TO DO after reading it? Is what I'm writing fulfilling those objectives? Does it show them what to do?" 2. Indexing: Be mindful of the difference between good sectional organization and indexing. The table of contents should suffice to locate major and even minor topics, *if* the material is organized correctly. An index is used to locate concepts and terms whose location isn't obvious from the table of contents or the organization of the document. There may in fact be no need to index a short tutorial, which can be read in its entirety quickly. Indexing is more important for longer works that a reader is not expected to digest in one sitting. Indexing can still be good in a smaller work as long as it is used judiciously. There is no need to be concerned about indexing every topic that appears in a section. Do not index redundantly against the table of contents. If you have a section that entitled "Using Application XYZ," you should not make an index entry for "XYZ, using." You should expect all readers will read the Introduction section of the tutorial, even if that is not always the case. Technical writers and editors, just like mathematicians or programmers, must at some point rely on a few basic postulates. A programmer rightly expects that if you use his code, you will read the licensing terms, and the function headers. We expect that someone who locates a tutorial will read the introduction to see that it matches the subject material. Therefore indexing material that should be found in the Introduction is redundant and unnecessary. Keep in mind that the Introduction should include a section for each major technology discussed in your tutorial. A tutorial should not have more than two or three major technologies involved, or else you should consider splitting it. 3. The Dreaded "Core Dump": Be wary of using terms with which a new user is not necessarily familiar, if your target audience includes new users. (Your target audience should be defined in the Introduction as required above.) Always write to the level of the *least* experienced user whom you reasonably expect to use your document. Remember that bytes are cheap, and if an explanation requires an extra paragraph, you should write it. See the "References" section below for a different take. A consistent problem with documentation is that it can easily become what my coworkers and I frequently refer to as a "core dump," in the sense that it is an unstructured output of all of the author's (many times considerable) knowledge of a subject. Be wary of this in writing/editing documents. "Core dumps" are not good documentation, and lose their authority quickly for discerning readers. The best way to avoid core dumps is to OUTLINE your document before you begin, as most of us did for composition classes as {pre,}teenagers. Flesh out your outline, and revisit it several times *before* you begin writing. Do the ideas progress logically? Are you fulfilling "dependencies" in the education process by discussing the basics first, before you move on to more complex material? Put yourself in the shoes of your least experienced reader. (If you are unable to remember a time when you were inexperienced, you need to find someone new to the subject to review your document and give you pointers!) 4. References: Using references to other authoritative documents is a good thing. An authoritative document might be another approved FDP tutorial or guide, an official work of the Linux Documentation Project, or a published work (of the dead-tree variety, including online offerings of dead-tree works). Messages on listservs, online forums, news sites, or other sources that do not have a rigorous editorial process are not good references. - - - - - Well, that's it for now. Maybe more later when I have a chance to pore over some of the other stuff in CVS. Have a great weekend! -- 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

FDSCo minutes 28 June 2005
by Karsten Wade 29 Jun '05

29 Jun '05

FDSCo meeting #fedora-docs irc.freenode.net 28 June 2005 Attendees: ========== Tommy Reynolds Karsten Wade Gavin Henry Paul Frields Stuart Ellis Updates: ======== XML normalization project now beta. See mailing list for beta testing request. Members needing advanced bugzilla access can currently join 'fedorabugs' group in Fedora Account System. Actions: ======== Paul: invite beta tests of XML normalization Karsten: task tracking process delivered for next meeting discussion Karsten: to train Rahul and Gavin on updating the website after the next meeting. This is open to all FDSCo/FDP members. This is the first steps in training Web publishers. Karsten: write up first draft of new docs2trans process. Karsten: still need to provide a better draft of staging server idea. Rahul: will start a Wiki page that can be the source for a Bugzilla Tutorial. Karsten: get FDP it's own bz category -- 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

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 June 2005