tidy-bowl - BETA invitation!
by Paul W. Frields
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/
18 years, 9 months
Back from my hiatus
by Thomas Jones
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
18 years, 10 months
Self-Introduction: Tatsuo Sekine
by SEKINE Tatsuo
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
18 years, 10 months
[ANN] docs-common/Makefile.common
by Tommy Reynolds
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
18 years, 10 months
OpenOffice.org update
by Paul W. Frields
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/
18 years, 10 months
Saxon?
by Tim Waugh
What's all this about changing xmlto to use Saxon instead of xsltproc?
How will that fix PDF output?
Tim.
*/
18 years, 10 months
Self-Introduction: Yoshinari Takaoka(a.k.a mumumu)
by Yoshinari Takaoka
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}
18 years, 10 months
Handling Multiple Document Versions in CVS ?
by Stuart Ellis
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
18 years, 10 months
Additional writing guidelines
by Paul W. Frields
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/
18 years, 10 months
FDSCo minutes 28 June 2005
by Karsten Wade
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/
18 years, 10 months
