Re: Call for updates - Release Notes
by Paul W. Frields
On Thu, 2006-11-30 at 16:43 +0000, Miloš Komarčević wrote:
> On 11/30/06, Dimitris Glezos <dimitris(a)glezos.com> wrote:
> > O/H Lauri Nurmi έγραψε:
> > > to, 2006-11-30 kello 04:55 -0600, Robert 'Bob' Jensen kirjoitti:
> > >> In about 1 week we would like to push a snapshot of the release notes
> > >> beats on the wiki to translation. If you have a beat on the wiki please
> > >> try to get any updates completed by Dec 7 23:59 UTC. The snapshot should
> > >> be going to Translation by Dec 9 23:59 UTC. Translations will be due
> > >> back 10 days later (Dec 19 23:59 UTC) for packaging and publishing.
> > >
> > > If I have translated the parts of release-notes required by the browser
> > > splash page, but nothing else, will my translation be packaged, and will
> > > I see the browser splash page in my own language?
> >
> > There are some people currently looking into this. Basically, we'll try to
> > separate the `po` file of the release notes from the other two because it's
> > significantly bigger. Unfortunately, it's not a trivial task because it affects
> > packaging, so I can't say if we will be able to do it at this time. If not, then
> > the separation will have to wait for FC7.
> >
> > Are there any other translators that would like to translate the messages of
> > "Browser Start page" and "System -> About Fedora" but don't have the
> > time/resources to translate the Release notes?
>
> Yes please, this would be very much appreciated, as I already
> mentioned on the list once.
>
> Serbian translation has had these parts (README, README-BURNING-ISOS,
> About, homepage etc., everything except the huge RelNotes section)
> ready for FC6. Unfortunately we just don't have the time and resources
> to handle the big section in the few days between freeze and release,
> and it doesn't make sense to work on it in the meantime since it will
> change considerably.
Sorry to be late to the thread here. I am starting with the homepage
and moving these into separate modules. I'm confident this will work
for an FC-6 update at some point (probably in January 2007), and we will
use that model for release 7 and going forward.
My plan is to modularize the following:
release-notes - only that content from the Beats on the wiki
readme - The standard descriptive README on CD/DVD #1
readme-burning-isos - Helpful information for the mirrors on burning CDs
about - The "About Fedora" menu item
homepage - The browser splash HTML page
With the exception of "release-notes" (which already exists), I need
someone to create these modules in i18n CVS for us to populate with POT
once this work is done. (I have an account there with write access, but
if some additional ACL is used, please allow me to write to these
modules.)
cc'ing the f-docs-l for informational purposes.
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://fedoraproject.org/wiki/Board
Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject
17 years, 3 months
"Re: Contents of fedora-docs-list digest..."
by Sarat sethy
>From: fedora-docs-list-request(a)redhat.com
>Reply-To: fedora-docs-list(a)redhat.com
>To: fedora-docs-list(a)redhat.com
>Subject: fedora-docs-list Digest, Vol 34, Issue 14
>Date: Wed, 13 Dec 2006 12:00:31 -0500 (EST)
>
>Send fedora-docs-list mailing list submissions to
> fedora-docs-list(a)redhat.com
>
>To subscribe or unsubscribe via the World Wide Web, visit
> https://www.redhat.com/mailman/listinfo/fedora-docs-list
>or, via email, send a message with subject or body 'help' to
> fedora-docs-list-request(a)redhat.com
>
>You can reach the person managing the list at
> fedora-docs-list-owner(a)redhat.com
>
>When replying, please edit your Subject line so it is more specific
>than "Re: Contents of fedora-docs-list digest..."
>
>
>Today's Topics:
>
> 1. Re: Admin Guide / Accounts - call for feedback (Paul W. Frields)
> 2. Re: Admin Guide / Accounts - call for feedback (Vladimir Kosovac)
> 3. Re: Admin Guide / Accounts - call for feedback (Rahul Sundaram)
> 4. Re: Admin Guide / Accounts - call for feedback (Vladimir Kosovac)
> 5. IPv6 documentation (Peter Vrabec)
> 6. Re: IPv6 documentation (Rahul Sundaram)
>
>
>----------------------------------------------------------------------
>
>Message: 1
>Date: Tue, 12 Dec 2006 17:45:21 -0500
>From: "Paul W. Frields" <stickster(a)gmail.com>
>Subject: Re: Admin Guide / Accounts - call for feedback
>To: For participants of the Documentation Project
> <fedora-docs-list(a)redhat.com>
>Message-ID: <1165963521.15428.19.camel(a)localhost.localdomain>
>Content-Type: text/plain; charset="us-ascii"
>
>On Tue, 2006-12-12 at 05:36 -0800, Tommy Reynolds wrote:
> > Uttered "Paul W. Frields" <stickster(a)gmail.com>, spake thus:
> >
> > > On Mon, 2006-12-11 at 12:52 +0530, Rahul Sundaram wrote:
> > > > Vladimir Kosovac wrote:
> > > > > I have couple of sandboxed pages ready for your review/input at:
> > > > >
>http://fedoraproject.org/wiki/wiki/VladimirKosovac/StylingPage/WorkPage
> > > > For example, if I am doing web services administration, I would
>expect
> > > > to learn about system-config-httpd in that section along with the
>Apache
> > > > configuration details.
> > > That's an excellent point Rahul makes -- that our documentation should
> > > be largely task-based. Relevant material should be lumped together
> > > where possible and logical.
> >
> > Agree emphatically.
> >
> > What I detest is "feature-oriented" documentation that mostly walks
> > around the buttons and menus of a GUI, or is an elaborated bullet
> > list of each separate feature (even if the elaboration runs to pages
> > or chapters). I'm as guilty as anyone about doing this ("My name
> > is Tommy. Chorus: Hi, Tommy!") but I'm recovering ;-)
> >
> > Every button / menu / feature / asset was designed into the program to
> > provide a service, with a reason behind that decision. Document the
> > problem solved by the feature, et. al., and not the implementation.
> > Answer the question of "how do I foo", not the question "what do all
> > these buttons mean?"; then the "what are all these dials and switches"
> > question becomes moot.
> >
> > So, instead of this:
> >
> > o The FILE menu has an EXIT button.
> >
> > I'd prefer to see:
> >
> > o When you are finished, click the FILE/EXIT button to
> > save all your work and to gracefully terminate the
> > program.
> >
> > Just my $0.02e+27, YMMV.
>
>Yessirree! To harp on something (yet again), note how important this
>makes defining your audience and their core knowledge, skills, and
>abilities: Without that thatinformation, you can't tell what your
>audience can't do without in terms of instruction.
>
>--
>Paul W. Frields, RHCE http://paul.frields.org/
> gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
> Fedora Project Board: http://fedoraproject.org/wiki/Board
> Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject
>
17 years, 3 months
RE: FW: follow-up on OSDL DTL Documentation Framework
by Bastian, Waldo
Let's do
Tue Dec 12, 8am pacific / 17:00 Paris on #fedora-docs on
irc.freenode.net
Cheers,
Waldo
Intel Corporation - Channel Platform Solutions Group - Hillsboro, Oregon
>-----Original Message-----
>From: Karsten Wade [mailto:kwade@redhat.com]
>Sent: Wednesday, December 06, 2006 3:39 PM
>To: Bastian, Waldo; desktop_architects(a)osdl.org; fedora-docs-
>list(a)redhat.com
>Subject: Re: FW: follow-up on OSDL DTL Documentation Framework
>
>f-docs-l folks, please read below for the context of this message.
>
>On Wed, 2006-12-06 at 14:44 -0800, Bastian, Waldo wrote:
>> At the first DAM meeting we discussed ways to improve developer
>> documentation, and discussed a documentatation framework. A few weeks
>> back we had an IRC meeting on the same topic. It seems that currently
>> people within Fedora are looking at the same issue. For those of you
>> that will be attending the DAM-III meeting the next few days, this
might
>> be a good topic to revisit. In addition we can schedule a meeting for
>> next week on IRC to extend the discussion to those who aren't present
at
>> DAM-III. (Let's say Wed Dec 12, 8am pacific / 17:00 Paris on
>> #fedora-docs on irc.freenode.net?)
>
>I'm good for Tuesday 12 Dec. but not Wednesday 13 Dec. I can do
earlier
>on Thursday 14 Dec., such as at 0600 PST/1500 UTC or 0700 PST/1600 UTC.
>
>For Fedora folks, let's plan this meeting around my schedule first, and
>I'll report out to Fedora folks who cannot attend. Based on our first
>joint conversation, we'll see where to go next.
>
>- Karsten
>
>> Cheers,
>> Waldo
>>
>> Intel Corporation - Channel Platform Solutions Group - Hillsboro,
Oregon
>> -----Original Message-----
>> From: Karsten Wade [mailto:kwade@redhat.com]
>> Sent: Tuesday, December 05, 2006 6:51 PM
>> To: Bastian, Waldo
>> Subject: follow-up on OSDL DTL Documentation Framework
>>
>> Waldo:
>>
>> I was forwarded a message regarding $SUBJECT. We have been
discussing
>> much of these same issues in Fedora, on all levels. In essence, how
can
>> downstream projects/distros contribute toward/through a commons of
>> documentation.
>>
>> Right now we are working on some ideas of what we think Fedora wants
to
>> do, and we want to reach out to folks such as your project to
>> collaborate:
>>
>>
http://fedoraproject.org/wiki/DocsProject/WorkFlowIdeas/AdvancingtheProj
>> ect
>>
>> We're in #fedora-docs (I'm 'quaid') on irc.freenode.net if you have
some
>> time to drop by (or schedule a discussion) so we can see where our
>> various ideas and activities might mesh together.
>>
>> Thanks - Karsten
>--
>Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
> Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
> quaid.108.redhat.com | gpg key: AD0E0C41
>////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
17 years, 3 months
Problem with freenode?
by John Babich
Guys:
Is there a problem connecting to irc.freenode.net?
I've been trying for 15 minutes.
Thanks,
John Babich
17 years, 3 months
Re: FW: follow-up on OSDL DTL Documentation Framework
by Karsten Wade
f-docs-l folks, please read below for the context of this message.
On Wed, 2006-12-06 at 14:44 -0800, Bastian, Waldo wrote:
> At the first DAM meeting we discussed ways to improve developer
> documentation, and discussed a documentatation framework. A few weeks
> back we had an IRC meeting on the same topic. It seems that currently
> people within Fedora are looking at the same issue. For those of you
> that will be attending the DAM-III meeting the next few days, this might
> be a good topic to revisit. In addition we can schedule a meeting for
> next week on IRC to extend the discussion to those who aren't present at
> DAM-III. (Let's say Wed Dec 12, 8am pacific / 17:00 Paris on
> #fedora-docs on irc.freenode.net?)
I'm good for Tuesday 12 Dec. but not Wednesday 13 Dec. I can do earlier
on Thursday 14 Dec., such as at 0600 PST/1500 UTC or 0700 PST/1600 UTC.
For Fedora folks, let's plan this meeting around my schedule first, and
I'll report out to Fedora folks who cannot attend. Based on our first
joint conversation, we'll see where to go next.
- Karsten
> Cheers,
> Waldo
>
> Intel Corporation - Channel Platform Solutions Group - Hillsboro, Oregon
> -----Original Message-----
> From: Karsten Wade [mailto:kwade@redhat.com]
> Sent: Tuesday, December 05, 2006 6:51 PM
> To: Bastian, Waldo
> Subject: follow-up on OSDL DTL Documentation Framework
>
> Waldo:
>
> I was forwarded a message regarding $SUBJECT. We have been discussing
> much of these same issues in Fedora, on all levels. In essence, how can
> downstream projects/distros contribute toward/through a commons of
> documentation.
>
> Right now we are working on some ideas of what we think Fedora wants to
> do, and we want to reach out to folks such as your project to
> collaborate:
>
> http://fedoraproject.org/wiki/DocsProject/WorkFlowIdeas/AdvancingtheProj
> ect
>
> We're in #fedora-docs (I'm 'quaid') on irc.freenode.net if you have some
> time to drop by (or schedule a discussion) so we can see where our
> various ideas and activities might mesh together.
>
> Thanks - Karsten
--
Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
quaid.108.redhat.com | gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
17 years, 3 months
Munch 'N' Learn - 2006-12-09
by Paul W. Frields
Here's the raw log from Saturday's session. It was a trickle-in
attendance for a variety of good reasons, so we didn't get to cover as
much as we hoped. I would like to do another one soon -- votes for date
and time accepted!
= = =
<stickster> OK, on to XML... Have you both seen HTML, for example, by
using Ctrl-U (view source) in Firefox?
<jmbuser> yes
<stickster> XML is just another markup language, and in fact it looks
remarkably similar
<dtypos> yes
<stickster> XML itself doesn't tell you what kind of tags (like <this>
or <that>) you can use -- HTML is actually more specific, because it's a
document type unto itself
<jmbuser> ok
<stickster> XML is just a specification for marking up things. DocBook
XML is a specific document type -- like HTML -- that is VERY widely used
in the Linux world for documentation
<jmbuser> That is certainly true
<stickster> This is because it is plum full of incredibly useful ways to
mark up your writing, so that you can tell a command-line instruction
from an application name, or a procedure from an itemized list
<stickster> It was an XML document type written specifically for
producing technical documentation
<stickster> If you want to write in XML -- ANY XML document type -- you
should try to use an XML-aware editor
<jmbuser> ok
<stickster> There are many available, like Kate and Quanta for KDE,
Conglomerate for GNOME, jEdit... many others.
<stickster> Many long-time command-line junkies use a text terminal
style editor; Karsten and I both prefer Emacs, and Tommy and some other
folks prefer vi
<stickster> It's a purely personal choice
<stickster> But using an XML-aware editor makes writing in DocBook (or
any) XML *much, much easier.*
<stickster> Let's do a quick tutorial on some easy editing in Emacs as
an example. Would that be OK?
<jmbuser> sure
<dtypos> +1
<stickster> OK, if you don't have it installed, get it with the
Add/Remove Software tool. Otherwise, just start it up from your GUI
menu, or type "emacs" at a terminal.
<stickster> Oh crap
<stickster> I forgot one other thing
<stickster> Quit emacs, sorry about that
<jmbuser> ok
<stickster> Do this: su -c 'yum install psgml'
<stickster> That's a great add-on package that's highly recommended for
this next part! :-)
<stickster> Let me know when you're ready
<stickster> Once it's installed, just fire up Emacs again
<jmbuser> i'm running rpm -qa | grep psgml to see if it's installed
<stickster> jmbuser: You can actually just do "rpm -q psgml" which is
usually faster
<dtypos> it was already installed for me
<jmbuser> I'm installing it now,,,
<stickster> OK
<stickster> Obviously I can't teach all of Emacs in the time we have
today, but I will teach you some "survival skills" with the
understanding that we are focusing on the XML and not Emacs
<jmbuser> working...
<stickster> A very important key in Emacs is Ctrl-G (usually abbreviated
as C-g in Emacs documentation)
<stickster> If you're stuck at a prompt and you don't know what to do,
C-g will abort it
<stickster> The next most important keystroke is how to get out of
Emacs, which is C-x C-c
<stickster> OK, everybody ready to start a document?
<dtypos> yes
<jmbuser> sorry for my sloooowww connection - proceed and I'll catch
up :-)
<dtypos> no problem for me waiting a bit
<jmbuser> almost there
<stickster> jmbuser: It's OK, catch-up will be fast once you have the
package
<stickster> Emacs (and most other editors like vi and such) are VERY
customizable
<stickster> We haven't done any of that, so we'll manually tell Emacs
that we are going to be writing an XML file
<stickster> First, hit Ctrl-x, Ctrl-f (C-x C-f), which means "open a
file"
<stickster> The prompt at the bottom starts you off at your home
directory "~/"
<stickster> Add to that a file name; in this case let's use
"docbook-test.xml"
<stickster> Note that on the status bar, one line above the bottom, the
new mode "SGML Fill" appears
<vnk_fd> 1Q2w3e
<vnk_fd> oops
10:39 * stickster hates it when he types passwords in IRC buffers too
<jmbuser> john looks away hurriedly
<vnk_fd> \sorry I'm late guys
<vnk_fd> had to go out
<jmbuser> installed psgml!
<stickster> Emacs has many "modes," which basically are ways of mapping
keystrokes and other behavior in a special way for each type of file
<jmbuser> applications > programming emacs text editor
<stickster> jmbuser: +1
<stickster> So for example, there's a C/C++ mode, a Python mode, etc....
<stickster> vnk_fd: Make sure you have emacs and psgml packages
installed, then open a file with Ctrl-x Ctrl-f
<stickster> Call the file "~/docbook-test.xml" and you'll be caught up
<stickster> SGML mode is... OK, but it's not exactly what we want
<stickster> Let's just tell Emacs that we want XML mode in particular
<jmbuser> sorry c-f, c-c gives me find file
<stickster> jmbuser: Ctrl-x, Ctrl-f
<stickster> Read carefully :-)
<stickster> Find file: is the right prompt though
<stickster> Just enter a new file's name and that is what opens
<jmbuser> that's what i meant
<stickster> Ah, very good then
<jmbuser> ok
<stickster> Hit Alt-x (which is abbreviated M-x in Emacs docs, the M
stands for "Meta")
<stickster> M-x means "run this Emacs command"
<vnk_fd> ok, done
<stickster> For the command, type "xml-mode" and hit Enter
<vnk_fd> xml-mode
<stickster> Note that the mode has changed to the proper "XML Fill" mode
<jmbuser> ok
<stickster> Now, normally all this would be in a startup config file,
and you wouldn't have to do it. But we're starting very fresh :-)
<stickster> So, for the first line of the document, type (or copy and
paste) this:
<stickster> <?xml version="1.0" encoding="UTF-8"?>
<jmbuser> ok
<stickster> That's a very standard XML declaration that appears at the
top of most XML files. It's like a "magic string" that tells lots of
XML-aware programs and shell utilities what the file content is.
<stickster> Now, add this next line:
<stickster> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML
V4.4//EN" "http://www.docbook.org/xml/4.4/docbookx.dtd">
<stickster> (Copy and paste is a good idea) :-)
<jmbuser> works for me
<stickster> Once you hit "Enter" after the second line, some stuff may
happen in Emacs, yes? A "Parsing prolog" prompt, probably
<jmbuser> wow
<stickster> I don't know if you'll see color, but I do here, maybe
because of my particular configuration
<jmbuser> ended with fontifying done
<stickster> Disco
<dtypos> +1
<stickster> Let me tell you about a reference for you to read after
we're done...
<jmbuser> red & green
<jmbuser> ok
<dtypos> ok
<stickster>
http://cvs.fedora.redhat.com/viewcvs/example-tutorial/en_US/example-tutor...
<stickster> That's the start of a self-documenting DocBook XML file. If
you read it later, it will likely answer a lot of beginner questions
about why things look the way they do in a DocBook XML file.
<jmbuser> ok
<stickster> For now, let's just start our own document
<stickster> (Sorry, I keep getting phone calls)
<stickster> To insert an element, hit C-c C-e
<stickster> Notice that Emacs already knows the top-level element is an
<article>
<stickster> Because we told it so in the DOCTYPE declaration
<stickster> Just hit Enter to confirm
<stickster> Notice that a big comment block appears, telling you all the
things that are legal to use here
<jmbuser> yeah!
<stickster> There may be an even faster way to do this, but what I do is
hit the following keys: Home, C-k
<stickster> C-k "kills" to the end of the current line, so it gets rid
of that whole comment
<stickster> Don't worry, I'll show you how to get that list back in a
more useful way
<jmbuser> done
<stickster> Hit C-c C-e again to "insert element"
<dtypos> ok
<stickster> Now you get a prompt with nothing filled in, because there
are many choices you can use
<stickster> If you hit the Tab key, you'll see a list
<stickster> Keep hitting Tab to scroll the list -- when you reach the
end and keep hitting Tab, it starts over again at the top
<stickster> Once you see what you want, you can type the first few
letters and hit Tab again for auto-completion
<stickster> Let's insert a title. Type "tit" and then hit Tab to
complete
<jmbuser> works
<stickster> Notice logically what we are doing -- declaring a title for
our article. Makes sense, right?
<jmbuser> sure
<stickster> Note that the cursor magically puts itself right where you
need to type
<stickster> "My Test Article"
<stickster> (Without the quotes, sorry)
<stickster> Now hit the End key to move to the end of the line, and hit
C-c C-e again to insert another element
<stickster> Tab will get you that magical list
<stickster> Let's just put in a paragraph, so type "para" (or "pa", Tab)
to insert it
<jmbuser> ok
<stickster> Now type some stuff in the middle. Don't worry about
anything except typing. Emacs will take care of wrapping and everything
else for you.
<glezos> hi all. sorry for being late.
<stickster> glezos: np, but I am almost out of time
<glezos> stickster, if I can be of any help, just tell me.
<stickster> OK, does everyone have some information in their <para>
element now?
<jmbuser> yes
<dtypos> ok
<vnk_fd> ok
<stickster> To save and exit, you can either use the GUI menu if you're
a loser (HAH! jk), or the following keys: C-x C-s to save the document
<stickster> And then (remember?) C-x C-c to quit Emacs
<stickster> Congratulations, you just wrote your first DocBook XML
document!
<jmbuser> done
<jmbuser> cool
<dtypos> fine
<stickster> Now, here's some stuff you can do to check your work.
(Normally, you would do this inside Emacs, but we're trying to keep it
simple for now.)
<stickster> Open a terminal
<stickster> We're going to "validate" our document -- that is, check
that not only have we written correct XML (where every open <tag> has a
closing </tag>), but that it follows the DocBook specification properly
<stickster> We can use the xmllint command for this
<stickster> Type this command:
<stickster> xmllint --noout --valid docbook-test.xml
<stickster> You should get no output, which means your document is
valid!
<jmbuser> yessiree
<vnk_fd> valid here
<stickster> xmllint's normal method is to output the r"
<stickster> oops
<jmbuser> oops?
<stickster> xmllint's normal method is to output the result tree, i.e.
your parsed document, but we don't want to see all that, just to know
that it's valid
<jmbuser> got it
<dtypos> valid
<dtypos> (no outpout)
<stickster> Now let's turn that DocBook into HTML -- use this command:
<stickster> xmlto html docbook-test.xml
<stickster> You should get the following output: "Writing index.html for
article"
<stickster> Then fire up your Web browser and point it at
file:///home/<username>/index.html
<jmbuser> true
<stickster> (substitute your username)
<vnk_fd> done
<dtypos> nice
<stickster> Lookee there, we just built HTML out of our DocBook article!
<vnk_fd> that's default docbook style?
<jmbuser> It's alive!
<stickster> The ONLY difference between what we all just did, and what
FDP does with its toolchain, is a matter of document length, some
stylesheets, and automation. The concepts are exactly the same.
<stickster> vnk_fd: correct
<jmbuser> ahhh
<vnk_fd> ah get it - our styles are in docs-common in cvs?
<stickster> vnk_fd: Exactly!!!
<stickster> That's where all the pieces that do our specific building
are
<vnk_fd> too easy, just to learn tags, then
<stickster> Including XSL (XML Stylesheet Language) templates that alter
the XML a bit on their way through the transformation process
<jmbuser> templates, you say?
<stickster> vnk_fd: That's all you have to do -- and most people only
learn the 15-20 elements/tags they use all the time
<stickster> jmbuser: Yeah, XSL is cool but unfortunately I'm out of time
for today
<jmbuser> stickster: thanks for the tutorial
<stickster> The reason we like XML so much over the wiki is that the
wiki only has, what? like, ten or so tags you can use, total
<dtypos> thanks very interesting lesson indeed
<stickster> DocBook has over a hundred, I think
<jmbuser> true
<vnk_fd> stickster: as we go, should we send questions directly to you
or to the list?
<stickster> vnk_fd: To the list, please
<jmbuser> ok
<vnk_fd> ok
<stickster> vnk_fd: I will definitely answer anything I can, and it will
help other people too
<dtypos> o
<dtypos> ..k
<vnk_fd> all right
<jmbuser> sounds good
<stickster> Don't worry if you don't like or get the hang of Emacs...
feel free to use what you want. I think Emacs rocks, but to each his
own
<dtypos> thanks again
<stickster> Use what makes you happy
<stickster> But definitely use DocBook! :-)
<stickster> All right, ciao everyone
= = =
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://fedoraproject.org/wiki/Board
Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject
17 years, 3 months
CVS + XML Munch 'N' Learn, 2006-12-04
by Paul W. Frields
This is the raw IRC log from our learning session last Monday. Just as
a (very late) reminder, we're having another session today at 1500 UTC
(10:00 a.m. US-Eastern).
= = =
<stickster> For anyone who wants to join in -- you may benefit from
doing the following, if you haven't already:
<stickster> su -c 'yum groupinstall "Authoring and Publishing"'
<stickster> su -c 'yum install gobby cvs'
<stickster> Give me 60 sec here..
<stickster> OK
<stickster> Anyone within the sound of my voice... :-)
<horadrim> installing the Authoring group, gobby and cvs are already
there
<stickster> OK... Run gobby and connect to the following host:
marilyn.frields.org
<BobJensen> stickster: How long are you thinking this will be?
<BobJensen> stickster: I want to take part but not sure if my wife has
other plans for my time
<stickster> ~55 min.
<stickster> I have to be done by then for dinner :-)
<BobJensen> OK
<stickster> All righty then, horadrim, are you good to go?
<stickster> CVS is for revision control. Much like a public library,
many people can check out, examine, play with, and check in materials.
<horadrim> still running the yum update but should be ok 5-10 minutes
for it to finish
<stickster> horadrim: OK, that shouldn't be a problem
<stickster> The normal cycle for CVS is this:
<stickster> 1. Check out one or more "modules" of
{code,content,whatever}
<stickster> 2. Make changes in the local copy (on your computer)
<stickster> 3. Test changes (!!!)
<stickster> 4. Update to make sure your local copy is fresh
<stickster> 5. Commit changes to the repository
<stickster> If anyone has questions, just shout them out at any time
<stickster> A checkout is where you take a copy of what's in the
repository onto a locally accessible disk (usually your hard disk)
<stickster> You can do whatever you want to this copy, and nothing
changes in the remote repository until you "commit" those changes
<stickster> When you do an "update," you are asking the remote
repository to send down any changes that may have happened since the
last time you did an update
<stickster> In MOST cases, the changes are simply patched in to your
local copy
<stickster> If the change is unresolvable -- for example, if you made a
local change that is in conflict with an update from the repository, you
get a warning from CVS
<stickster> During an update, you'll see letter codes next to each file
that was changed -- a common code is "U" for something that has been
successfully updated
<stickster> or "P" for something that has been updated with a simple
patch
<stickster> But if you have an unresolvable conflict, you'll see the
letter "C," which means you'll need to visit the file to see what
happened.
<stickster> The changes that couldn't be resolved are bracketed by very
visible <<<<<<< and >>>>>>>> lines
<stickster> I don't want to go too much further until we do a checkout
<stickster> BobJensen, horadrim: Does this make sense so far?
<BobJensen> yes
<horadrim> yes
<stickster> Cool!
<stickster> Since everyone presumably has CVS installed, let's do a
test.
<stickster> Run the following commands: cd && mkdir -p fedora/docs/
<stickster> And: cd ~/fedora/docs/
<stickster> Then do this: cvs
-d :pserver:anonymous@cvs.fedoraproject.org:/cvs/docs co docs-common
mirror-tutorial
<stickster> (that's one line, I don't know if the buffers handle it
right) :-)
<horadrim> it's ok
<stickster> It may take a little while for your system to download
everything
<horadrim> done here
<stickster> Excellent
<stickster> The "-d :pserver:...(blah)..." option is a method of
connecting to the CVS server -- in this case, using an anonymous login.
<stickster> This connection method means you won't be able to commit any
changes -- which is fine for now.
<stickster> The "co" is the CVS command we're running, short for
"checkout"
<stickster> That's followed by the two modules we were choosing.
<stickster> If you didn't know what modules to use, you could try this:
<stickster> cvs -d :pserver:anonymous@cvs.fedoraproject.org:/cvs/docs co
-c
<stickster> That would give you a list of all modules. It's actually in
a tabular form -- the left-most entry is a module name, and following
that is a list of any alias content.
<stickster> That's not very important, other than to note that it's
possible for a CVS repository to give users a "shorthand" that allows
them to check out a whole bunch of directories at once with a single
module name
<stickster> *: Make sense so far?
<horadrim> yup
<stickster> OK... let's look at the content of a module. Don't worry
about "docs-common" for right now, although it's full of interesting
things... for later :-)
<stickster> So do: cd ~/fedora/docs/mirror-tutorial
<stickster> horadrim: Did gobby finish installing?
<horadrim> yes
<stickster> OK, go ahead and run it, and connect to hostname:
marilyn.frields.org
<stickster> The default port should be correct
<stickster> Cool
<stickster> All right, I'm going to load up some documents in there as
we go along. You'll have copies on your drive now for later reference.
<stickster> OK, I just loaded the "Makefile" file.
<stickster> There are only a couple things you need to write a new
document from scratch -- this Makefile is one of them. If you decide to
start working with DocBook in CVS, you can copy this file from an
existing module and just make some minor changes. Everything will then
work auto-magically :-)
<stickster> Everything behind a # is a comment, of course :-)
<stickster> Let's look at the important lines. They declare some
settings, or variables, for use by the make command.
<stickster> (Oops, I should have made sure people installed "make" with
yum, too. Well, do it now if you have time.)
<stickster> OK, back to the Makefile.
<stickster> The first variable, "DOCBASE", is the name for the parent
(or main) XML file for your document. It's considered the Right Thing
To Do to name your DOCBASE, your main XML file, and your module the same
thing when possible
<stickster> Although you'll find a couple places where we've broken that
rule :-)
<stickster> So here, what I'm telling our build tools is that my main
XML document is called "mirror-tutorial.xml". You just leave off the
".xml" part.
<stickster> The next line "PRI_LANG" declares the _primary language_ for
the document
<stickster> It's usually "en_US" for US English, but that is not a
requirement
<stickster> *: OK so far?
<horadrim> yes
<stickster> BobJensen is busy so I'll assume he's logging :-)
<stickster> OK, next line, "OTHERS", is where we define any other
languages for this document that are to be built.
<horadrim> i'll save the transcript ain any case
<stickster> horadrim: Thanks, I'll be posting it to f-docs-l as well
<stickster> Note that translations for these OTHERS don't happen
magically -- translators have to come in and build "PO" files, which
contain translations for all the strings (text) in the original XML
document(s).
<stickster> So for a document that you're starting from scratch, this
may well be blank, i.e. "OTHERS = "
<horadrim> i know too well the L1ON world
<stickster> very good :-) I won't belabor that point then :-D
<stickster> OK, the next line, "DOC_ENTITIES" is where you note the name
of any document-specific entity file.
<stickster> An "entity
<stickster> Oops
<stickster> An "entity" is basically somewhat like a "macro" in XML.
It's a way of using a shorthand abbreviation where you mean some larger
bit of text that you don't want to have to keep typing (or risk
misspelling) over and over
<stickster> There are a few different kinds of entities, but the ones we
use a lot look like this: &FED;
<stickster> They have an ampersand '&' in front and a semicolon ';' at
the end
<stickster> They don't have to have an all-caps name, but it helps
because it will be easy to see in the middle of other text
<stickster> In this example, &FED; is our entity that resolves to the
word "Fedora"
<stickster> Similarly, &FC; ==> "Fedora Core"
<horadrim> ok
<stickster> OK, so the point of all that is you can have entities that
are very specific to your document, and keep them in a file whose name
you put on this line, "DOC_ENTITIES"
<stickster> As you can see, I have such a file,
"doc-entities.xml" (Again, leave out the ".xml" part)
<horadrim> here DOC_ENTITIES just states doc-entities so should it be
smtg like &FED;
<stickster> horadrim: It's a filename, so it means that I have a
document-specific entities file called "doc-entities.xml"
<horadrim> ok just populate a file and reference said file in there
<stickster> horadrim: Exactly
<stickster> We'll look at the file later
<stickster> Next is a part that looks a little scary, but it's not as
bad as it seems
<stickster> All you need to do is add lines to the "XMLFILES-${1}"
definition for any DocBook files which make up your document
<stickster> In this case I have only one.
<stickster> The ${1} is the scary looking part -- to make a long story
short, it just means "insert language (directory) name here"
<stickster> Since this document's primary language is en_US, this means
that the XML file list is only one file, "en_US/mirror-tutorial.xml"
<stickster> Note that ${1} == en_US , and ${DOCBASE} == mirror-tutorial
<stickster> You don't have to use the ${DOCBASE} variable here, you
could just do this:
<stickster> (watch gobby)
<horadrim> ok
<stickster> Using DOCBASE means that someone can copy this Makefile for
any module with only one XML file named after the module, and it will
Just Work(tm) :-)
<horadrim> pretty regular use of a $VARIABLE
<stickster> Exactly
<stickster> So, the whole thing's in a template, which is why we're
using ${1} -- it's a Makefile parameter that is used during build,
meaning "insert language here"
<stickster> Finally, we have an "include" statement to grab all the
goodies from our (much longer and more complicated) Makefile.common,
which includes all the rules for building HTML, validation, etc....
<stickster> On to the document, then, OK?
<horadrim> indeed
<stickster> OK, how familiar are you with XML in general?
<stickster> (zero is a perfectly acceptable answer)
<horadrim> generic idea...i also read the fedora mag extracts
<stickster> Awesome
<horadrim> i am somwhat familiar with markup languages
<stickster> That's great... you'll find this pretty easy then
<horadrim> i think i can pretty much go through easily
<stickster> OK, here's the 10,000m fly-over then :-)
<horadrim> i'm sad i work with PErforce (SCM) and document management
software
<stickster> The "rpm-info.xml" file is a requirement. It follows a DTD
(you'll see the definition at the top of the file we have open) that's
in the docs-common module you checked out
<stickster> If you're going to edit XML, you'll want to use an XML-aware
editor -- there are many of them, some GUI, some text
<stickster> I prefer Emacs, as does Karsten (quaid); some prefer vi/Vim
<horadrim> i tend to use Vi
<stickster> Others like Kate, or quanta, or...... etc
<stickster> Great
<horadrim> as long as it does the job...
<stickster> actly.
<stickster> Oops... exactly.
<stickster> The thing about these editors is, they are XML-aware and
will "validate" your entry
<horadrim> fair enough
<stickster> They understand DTD's and if you use the appropriate
keystrokes, they will make sure you don't put an illegal or invalid tag
in your document in the wrong place
<stickster> This makes writing any XML file with a DTD much easier --
you don't really need to learn more than a few tags, because if you ever
need another one, your editor will tell you what's legal to use in your
current context
<stickster> The rpm-info.xml file is a good example. You don't really
want to memorize the DTD; just use your editor, copy the first couple of
lines from an existing rpm-info.xml file, and then let your editor do
the hard work.
<horadrim> don't worry...no intention of re-inventing the wheel
<stickster> OK, so this file is required.
<stickster> Notice I also opened the "doc-entities.xml" file, which is
only required because my Makefile says I'm using it
<stickster> I think this should make a little sense... note for example,
the definition for the &DOCDATE; entity
<stickster> In this case, it's defined as "2006-08-07"
<horadrim> was indeed looking at this
<stickster> Note also the &DOCID; entity definition, which uses other
entities we've defined here
<stickster> And keep in mind that we have a <group> element to group
entities together, but it's really up to you how you want to do that; we
don't have rules, although I like to see the "Revision markings" in one
group
<stickster> All right, moving on...
<stickster> The actual DocBook XML file (finally!) is in
"mirror-tutorial.xml"
<stickster> You'll probably end up just copy/pasting the first 10 lines
from an existing document, which is a perfect way to start
<stickster> And then, as we discussed earlier, let your editor do the
hard work
<stickster> If you get lost while doing any of this, just shoot a
question to the list or here in IRC
<horadrim> makes sense...so you keep track of version/subversion by
manually modifying the doc_entities then....then
<stickster> horadrim: Ah, that's the rub. There's actually two places
we keep track of it -- which, yes, is stupid and we will try to change
this
<stickster> You put it in the doc-entities.xml for use in the document
itself, and also in the rpm-info.xml file in the <changelog> section
* stickster thinks we will need to cover the XML content in a second
tutorial next week, if that's OK
<stickster> Don't feel you need to understand all of this yet
<horadrim> yup it's fine
<quaid> stickster: we could make a regular tutorial time/place, rotate
who is giving it, and dump the whole log to the world for edification :)
<stickster> quaid: nod I'll be posting this log to f-docs-l again like
last time
* quaid supposes we can recycle topics, too
<stickster> absolutely
* quaid goes quiet again :)
<quaid> stop ruining the log
<stickster> horadrim: So, what I've given you was part CVS and part
organization of a module you checked out
<horadrim> do you have a mcro that makes sure doc_entitities and
rpm_info are in sync re version/subver at build time?
<stickster> Good question!
<stickster> I don't think we do, but I know how to do it with some XSLT
<stickster> That's a great to-do item
<horadrim> we probably need some kind of automated sanity check for
this?
<stickster> Would you mind putting it in Bugzilla for me? You can log
it to Product "Fedora Documentation", component "toolchain-devel"
<horadrim> ok
<stickster> horadrim: Absolutely
<stickster> In fact, it would probably be best if we only tracked this
in one place, come to think of it
<stickster> I think that's do-able, actually
<horadrim> shame there is no auto-increment...
<stickster> Feel free to make that a wish list in your Bugzilla entry,
it will help remind me
<horadrim> lol deal!
<stickster> Actually, I have a "make clog" that will update
rpm-info.xml, but it won't do anything useful to doc-entities.xml
<stickster> Oh, I remember why!
<stickster> It's because my documents are using a special
&BUG-REPORTING; entity that fills in this information -- it's not
technically required so that's why there's no automated tool to tie the
two revision number tracking pieces together
<stickster> But that doesn't mean this doesn't merit a second look, so
do file that BZ
<horadrim> a sanity-check like that could probably mitigate the risk of
human error...a simple warning would probably do
<stickster> Definitely
<stickster> horadrim: OK, so if you want to forge ahead, and you're
sitting in ~/fedora/docs/mirror-tutorial, you can run "make help" to see
some of the targets available
<stickster> There's a lot of them, and only some will work in this case
<stickster> The main ones are "make validate-xml" and "make html" if you
want to see a couple things in action
<stickster> At this point, my advice is for you just to look at the XML
files and try to understand small parts at a time
<stickster> Ask plenty of questions on the list, it will help everyone
who lurks :-)
<horadrim> don't worry, i'll have a play
* stickster has to run to dinner
<stickster> Thanks for being a willing audience
<horadrim> enjoy! and thanks for the tutorial
<horadrim> it's kind of fun
<stickster> Looks like quaid is around, and he taught me most of what I
know, so feel free to shoot him questions too
* stickster bolts
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project Board: http://fedoraproject.org/wiki/Board
Fedora Docs Project: http://fedoraproject.org/wiki/DocsProject
17 years, 3 months
comments on 'directory structure'
by Dimitrios Typaldos
I would like to include some ideas/proposals that maybe could improve the Directory Structure:
Naturally, there are two different types of approach in presenting the directory hierarchy :
1 - deploying the tree directory from root to branches giving a short explanation for each of them
2 - expanding the way the work started already by selecting a general list of 'concepts' and try to map them in the various directories to which a relevant association exist. For instance :
system monitoring -> /proc/ ...
help ->: info and man pages directories
etc..
I think the description can be done in both schemes, though definitely the most relevant is the one already existing (e.g. No 2 above). Maybe a good idea is to avoid mapping simple notions otherwise we are risking to end with an infinite list of 1->1 associations of limited interest.
- Adding information on hard and symbolic links that ease the directories' access regardless the absolute position of the including files for the user's point of view (can be added in the introduction ?)
- Further explanations on the specific content and relevant comments of the directories' entries
- In the 'Additional resources' I would find good to provide some useful links to other chapters with sharing entities
- few words about the effect of permission privileges dependances among parent directories and daughter branches when these are set
- (??) list of directories whose improper alteration could critically compromise the system's performance
Any comments positive or negative are welcome.
Dim
o-----------------------------------------------------------------------------------------------------o
pub 1024D/6A7B898C 2006-11-16
Key fingerprint = F892 27EB 871A 3C16 B18E 3AD5 3A6A 3F77 6A7B 898C
uid Dimitrios Typaldos (Encrypted)
sub 2048g/4773BB57 2006-11-16
____________________________________________________________________________________
Have a burning question?
Go to www.Answers.yahoo.com and get answers from real people who know.
17 years, 3 months
Self Introduction: Igor Miletic
by Igor Miletic
Full Name: Igor Miletic
City, Country: Ottawa, Canada
Profession: Electrical Engineer, student
School: Carleton University
My goal in Fedora docs project is:
- to translate documentation in Serbian language
- also time permitting I would like to help creating more
documentation where needed
My historical qualifications:
- I have been translating Fedora to Serbian for the last year
- I have few technical publications in peer reviewed conferences
- good computer skills, beginner level c/c++, lisp, java coding
skills (mostly as a side effect of the profession rather than a computer
scientist)
GPG KEYID and Fingerprint
[imiletic@miletic .gnupg]$ gpg --fingerprint 7C08C57E
pub 1024D/7C08C57E 2006-09-11
Key fingerprint = DA3D 54D1 D43B 06EF 7FA8 6924 3D68 184B 7C08 C57E
uid Igor Miletic (Сиви Соко) <grejigl-gnomeprevod(a)yahoo.ca>
sub 2048g/44BAFCBC 2006-09-11
17 years, 3 months