docs September 2005

docs@lists.fedoraproject.org

21 participants
33 discussions

Minutes FDSCo 20 Sep 2005
by Karsten Wade 21 Sep '05

21 Sep '05

FDSCo meeting 20 September 2005 irc.freenode.net, #fedora-docs Canonical schedule and tasks: http://fedoraproject.org/wiki/DocsProject/FedoraDocsSchedule Summary of Updates and New Tasks: ================================= * http://fedoraproject.org/wiki/DocsProject/Tasks explains a useful and preferred way for tracking FDP tasks. * FDP continues to pursue a toolchain that is both 100% free and in line with what the upstream DocBook developers are using. Tommy will continue his pursuit of help in getting Saxon and FOP compiled with gcj by going to an external list, docbook-apps. Surely someone somewhere is working on this, too. * Karsten is trying to get the final word on what translation process we are using for FC5 test1. Expect it to all happen manually through /doc/cvs, confirming that expectation with Sarah and Bernd. * Lots of recruiting going on for beat writers this week. Looking within the developers to supply and wrangle content. * Trying to create some process to make the Wiki -> FDP DocBook easier, look for Stuart's email showing MoinMoin -> XML output. That's as far down the list as we made today! Attending: ========== Gavin Henry (G2) Tammy Fox (tcf) Karsten Wade (quaid) Tommy Reynolds (megacoder) Stuart Elliss (elliss) Paul Frields (stickster) Regrets: ======== Mark Johnson (mrj) ## 30 ## -- 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

relnotes content list
by Karsten Wade 19 Sep '05

19 Sep '05

This new list receives all the content that flows into relnotes(a)fedoraproject.org: http://www.redhat.com/mailman/listinfo/fedora-relnotes-content I've asked Elliot to point relnotes@ to this address only. All other individual addresses are going to be dropped from that alias. Everyone who has already chosen to be a beat writer or otherwise needs this content flow is about to be subscribed by me to that list. I'm not including FDSCo members who have not signed up for a beat, as per my promise to start with a clean slate for this release. This list is likely going to start slow, but in the future it may be a great source for early, raw content that has other values to you. Feel free to join the list just to watch it grow. - 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 0

Self-Introduction: Scott Glaser
by Scott Glaser 19 Sep '05

19 Sep '05

Full legal name (as you use it is fine) Scott Glaser * Virginia Beach, VA, USA * Senior Engineer * Lockheed Marting * Your goals in the Fedora Project * What do you want to write about? * Just about anything that will make Fedora easier to understand for a New Users. * What other documentation do you want to see published? * That is hard to say, first I would like to assist in making the Fedora Core 4 Installation Guide a document that will help new users in installing Fedora Core with little or no assistance no mater what method of install they choose. * Do you want to edit for grammar/writing and/or technical accuracy? * I am willing to help the group in any way I can. * Historical qualifications * What other projects or writing have you worked on in the past? * I have done a bit of technical writing while an employee at Lockheed Martin. Mainly test procedures, but lately I have had to generate and edit some Linux/Networking training lessons and presentations as non-programmer I think the Documentation Project is a perfect fit for me as a way to contribute. * What level and type of computer skills do you have? * I am an electronics specialist that has learned how to use computers as part of my work. I am currently preparing to return to school as I realize that I still have a lot to learn about computers. I have a vast general knowledge in various computer platforms from PC to VME and have worked with just about every OS that is currently available. * What other skills do you have that might be applicable? User interface design, other so-called soft skills (people skills), programming, etc. * Being an employee of a major defense contractor I have numerous skills that may be of benefit. As I work with the US Navy I am pretty good a taking technical data and making it easier for the end-user to understand. I would say that I am pretty good at generating how-to documents. * What makes you an excellent match for the project? * I guess what makes me an excellent match for the project is the fact that I really enjoy helping people learn how to use Linux. I started with Redhat 6.x and have not turned back. * GPG KEYID and fingerprint pub 1024D/599000BD 2005-09-17 [expires: 2006-09-17] Key fingerprint = 61F5 C7DF 2F63 4A53 44D2 B9BE 3841 EA4F 5990 00BD uid Scott Glaser (Sonar_Guy) <sonar_guy(a)c-ccom.com> sub 2048g/A6676129 2005-09-17 [expires: 2006-09-17] -- Scott Glaser Fedora Core User Web - http://members.cox.net/sonar_guy/

3 5

A few nice bits in CVS
by Paul W. Frields 19 Sep '05

19 Sep '05

While I was on and in various planes and hotel rooms in Seattle I managed to cobble together a couple kibbles 'n' bits in the docs-common module that should make our documentation easier to read. One of the common complaints was that the revision history block on the title page made readers wade through a lot of material in which they weren't interested just to get to the real narrative. The revision history now is linked in the same manner as the legal notice, so people can get right to the table of contents as expected. (You can see the results in the "yum" and "jargon-buster" documents on the fedora.redhat.com web site now.) If you generate a "nochunks" version of the HTML, the revision history appears inline, just as the legal notice does. One tiny drawback is that the build process (i.e. "make") issues a warning about context. It's only a warning and does not affect the efficacy of the build. I'm sure this is a small problem easily fixed by someone who understands XSL better than I. That someone might even find a better way to accomplish the task, and if so, please have at it. In the meantime, if you have a docs-common/ module checked out of CVS, you should update it ("cvs up") now. If you have no idea what I'm talking about, then you need to speak up on the list so we can answer any of your questions and get you working on some of the good stuff! ;-) -- 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 5

Wha' happened?
by Paul W. Frields 19 Sep '05

19 Sep '05

Why do none of my documents now clean or build using the standard "make clean" or "make"/"make html" commands? I notice the Makefile.common in docs-common changed yesterday. Hints please? -- 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/

1 1

[ANN] New support for document translations
by Tommy Reynolds 17 Sep '05

17 Sep '05

Hello! The Fedora Docs Steering Committee has been discussing the best way to add support for multiple languages in the FDP material. The decision has been made to have the English and non-English translations to be in peer files: mydoc-en.xml mydoc-de.xml and so on. Translators will provide a complete mydoc-<locale>.xml file that we will just drop into the document directory. I have updated the FDP document building infrastructure to accomodate this. Now, a simple make(1) command will build any or all forms of the document (separate HTML files, a single HTML file, a PDF, or a tarball) for each supported language. The example-tutorial document has been updated for the new technique. Please review it before making changes to your own document. Most of the make-fu is in the "../docs-common/Makefile.common" file where it belongs. While you are welcome to browse it, you don't really need to be concerned with it unless you are curious. The per-document "Makefile" has gotten simpler. Only 3 lines are needed: LANGUAGES = en DOCBASE = example-tutorial XMLEXTRAFILES-en = should do the trick for an English file. After adding a German translation, the "Makefile" would look like this: LANGUAGES = de en DOCBASE = example-tutorial XMLEXTRAFILES-de = XMLEXTRAFILES-en = Note: All output files will be rendered using UTF-8 encoding for all of the locales defined in the ${LANGUAGES} macro. So, if you need a more precise locale, use something like: LANGUAGES = en_US en_GB and name your files "mydoc-en_US.xml" and "mydoc-en_GB.xml". As always, if you have trials and tribulations, or you just want to ask, do so on this list so that everyone may benefit. Cheers!

1 0

XML style guide
by Karsten Wade 16 Sep '05

16 Sep '05

Mark Johnson and I are working on an update to the DocBook XML style guidelines. These are currently mixed between the Fedora Documentation Guide[1] and the example-tutorial in CVS. Our objective is to make a complete, unified, canonical, and community- influenced set of style guidelines. Our other objective is to use these guidelines internally. One of the interesting effects of having a good toolchain and documentation about how-to document is that FDP is being used by people for internal or other non-Fedora documentation needs. I think that is *so* cool. Open source content is more than just technical talk. It includes marketing talk, project management talk, process talk, style, usability, and design talk, philosophy talk ... well, that last one is at the core of the free software movement, an open, conversant philosophy. Anyway ... You are watching this DocBook XML style guidelines unfold in front of you on this mailing list, with your participation encouraged. Thanks - Karsten [1] http://fedora.redhat.com/participate/documentation-guide/ -- 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

Release Notes - A New Era
by Karsten Wade 16 Sep '05

16 Sep '05

It's time to start gathering notes for FC5 test1 and final release notes. There are some very good changes and additions to the process, to make participation easier. There are also some new things that you, as developers, must do. Highlights: * Wiki used to gather notes, - not just bugzilla! * Using *docs* keyword in CVS commit logs - new magic from Elliot! * Translations of relnotes included in fedora-release package * Sub-projects responsible for supplying a beat writer - You can coerce them, you can hijack them, but you have no content in the relnotes without them http://fedoraproject.org/wiki/Docs/Beats/HowTo covers much of this same material. Don't know what the relnotes beats are? http://fedoraproject.org/wiki/DocsProject/ReleaseNotes/Beats * Changes * ** Wiki Used to Gather Notes ** Beat writers are now able to use the tree at http://fedoraproject.org/wiki/Docs/Beats to gather raw input and form it into content for the release notes. These pages have a light structure that generally goes one layer deep, for example, Docs/Beats/Kernel is for the kernel portion of the release notes. This maps nicely to one <section> or <chapter> in XML. Beat writers are free to add and change sub-pages, as they need. Other contributors can do the same. The only requirement to edit is that the user be registered and logged in. These beat notes are ongoing workspaces. A snapshot is taken just prior to freeze for translation, and the content is merged into the overall DocBook/XML-based release notes. These XML release notes are canonical, but necessarily behind the raw Wiki pages. Beat writers need to keep the content cleaned-up and relevant. You want to watch your page and all sub-pages using the pattern Docs/Beats/Beatname.* in your "Subscribed wiki pages" of your UserPreferences. Wiki-help for beat contributions is on-topic for #fedora-docs. ** Highlighting Your CVS Commit for Documentation ** The next time that you make a CVS commit that fulfills a feature, fixes a bug, or otherwise is worth noting in the relnotes, try this trick. Put the keyword *docs* in the commit log message, and a copy of the commit is sent to relnotes(a)fedoraproject.org . The beat writers and editors parse the note into the proper place, or open a bugzilla report to track the note suggestion. This is a must-do for Core packages, look for opportunities. Extras packages are encouraged to use this at milestone events, etc. This page tells more about what to highlight for *docs*: http://fedoraproject.org/wiki/DocsProject/WhatToDocument ** Use Bugzilla to Highlight an Existing Report ** Just add relnotes(a)fedoraproject.org to the Cc: field. We'll parse this into the proper place. ** File a Bug Report ** This small URL is for a pre-filled bugzilla report. This is a great way to submit a note or idea for the release notes, since conversations and solutions are logged. Bugs are set to block a master tracker for the release. http://tinyurl.com/89dkk ** Translations With Release ** The schedule for the release notes now includes time for translation, so that the translated content can appear within the fedora-release package. At the top of the shipping release notes is a prominent link to the latest online version of the relnotes. This helps to counter the problem of having to freeze the release notes so long before test and release. We'll do a Web-launch of a latest set of release notes to time with the distro releases. * New For Developers * You are responsible within your Fedora sub-project to produce content for the FC release notes. Someone from your team needs to step-up and take the role of beat writer, or find someone interested in helping your project to take that role. Being a beat writer is a _fantastic_ and reasonable way to get involved with an open source project. It's designed to be bite-sized for the average volunteer. Ultimately, the amount and quality of content in the release notes is your responsibility. The FDP takes all the rest of the responsibility -- merge, edit, convert to XML, get translated, build multiple output formats, package for fedora-release, publish to Web, make downloads available, and support with ongoing updates as needed. ** Deadline to Pick Beat Writer ** By 23 September, all sub-projects need to have picked the person who is the beat writer for your part of the release notes. This is effective for FC5 and forward. In other words, a beat may be handed-off, it may not be abandoned. 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/

1 0

Minutes for 13 Sep 2005 meeting
by Karsten Wade 15 Sep '05

15 Sep '05

FDSCo Meeting 13 September 2005 Attendees: ========== Gavin Henry (G2) Tammy Fox (tcf) Karsten Wade (quaid) Tommy Reynolds (MegaCoder) Stuart Elliss (elliss) Mark Jonson (mrj) Guests: ======= Rahul Sundaram (mether) Regrets: ======== Paul Frields Updates: ======== * New release notes beat writers are being recruited. Tools now include the Wiki, which we hopes greatly increases participation. * Meeting is trying to use the Wiki schedule at http://fedoraproject.org/wiki/DocsProject/FedoraDocsSchedule as the agenda. This is the practive of other project committees. Worked pretty well. List is now canonical for all FDSCo tasks. * http://fedoraproject.org/wiki/DocsProject/Tasks is the page that describes how tasks are managed. http://fedoraproject.org/wiki/DocsProject/MasterTasks is deprecated * We need help with getting FOP and Saxon compiled with gcj * Staging server to provide Docs Rawhide is in the works. This will provide builds of all versions of a document, publishing fixed URLs of the output that includes HTML, tarball, PDF (where possible), and all available languages. * Details about translation for FC5 release notes and docs are being worked. Tommy will modify the Makefile to make it i18n'ized. * Keyword for CVS commit logs is fixed at *docs* and will be announced ASAP. * Karsten to make first relnotes announcement, to include details of how new process works. ## 30 ## -- 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

Java developer needed to help with Fedora Docs Project infrastructure
by Tommy Reynolds 13 Sep '05

13 Sep '05

Hi, All! Over at the Fedora Docs Project, we have a problem that we think you can help with. Our developers use XML DocBook so that we can generate both HTML and PDF forms of the document from the same originals. The HTML generation works great, but the PDF generation is broken. Our current tool "xmlto" uses TeX to render to PDF, but that hasn't been maintained for a long time. We can use Apache FOP for the rendering but don't want to use the JVM version because it doesn't have an open license. So, here is how you could help. We'd first like to get Apache FOP native compiled using gcj and then maybe add in some open-source PNG or JPG rendering libraries. If you would like to help, you can reply on this list or contact me privately at: Tommy.Reynolds(a)MegaCoder.com I look forward to hearing from you!

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