docs December 2006

docs@lists.fedoraproject.org

26 participants
50 discussions

Re: Call for updates - Release Notes
by Paul W. Frields 15 Dec '06

15 Dec '06

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

3 2

"Re: Contents of fedora-docs-list digest..."
by Sarat sethy 13 Dec '06

13 Dec '06

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

1 0

Admin Guide / Accounts - call for feedback
by Vladimir Kosovac 13 Dec '06

13 Dec '06

Greetings, Motley Crew! I have couple of sandboxed pages ready for your review/input at: http://fedoraproject.org/wiki/wiki/VladimirKosovac/StylingPage/WorkPage As Karsten suggested, probably easier to review smaller chunks - thus this call. Of course, all suggestions are welcome and appreciated. Thanks | vnk |

4 10

RE: FW: follow-up on OSDL DTL Documentation Framework
by Bastian, Waldo 12 Dec '06

12 Dec '06

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 >////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

2 1

Problem with freenode?
by John Babich 12 Dec '06

12 Dec '06

Guys: Is there a problem connecting to irc.freenode.net? I've been trying for 15 minutes. Thanks, John Babich

1 0

Re: FW: follow-up on OSDL DTL Documentation Framework
by Karsten Wade 11 Dec '06

11 Dec '06

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 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

2 4

Munch 'N' Learn - 2006-12-09
by Paul W. Frields 10 Dec '06

10 Dec '06

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-tutoria… <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

1 0

CVS + XML Munch 'N' Learn, 2006-12-04
by Paul W. Frields 09 Dec '06

09 Dec '06

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

1 0

comments on 'directory structure'
by Dimitrios Typaldos 08 Dec '06

08 Dec '06

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.

3 3

Self Introduction: Igor Miletic
by Igor Miletic 08 Dec '06

08 Dec '06

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

4 11

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 December 2006