Subject:
Re: overwhelmed by the LDP author guide
From:
Tabatha Marshall ####@####.####
Date:
14 Jun 2003 00:57:15 -0000
Message-Id: <1055552413.17844.39.camel@mysticchild>
On Thu, 2003-06-12 at 21:37, Emma Jane Hogbin wrote:
> On Thu, Jun 12, 2003 at 04:05:32PM -0700, Tabatha Marshall wrote:
> > I just wanted to point out that even if you can't get this into XML or
> > SGML yourself, someone on the review team can probably give you a hand.
>
> I want to give it a fighting chance first. :) I know that the words need
> to be modified as well (I can't exactly refer to the sidebar anymore).
Glad to hear it! In fact, speaking from experience, the best way to
learn is when you have something you specifically need to do. If you
haven't already heard, there's a docbook mailing list at the LDP for
those *burning* questions too!
After reviewing documents for basic grammar and spelling, I also like to
look for words that can benefit from the use of tags. Most people
overlook <filename>, <varname>, <option> and even <quote>, to name a
few. The tags offset the text to another style which gives them more
prominence, and adds clarity. DocBook's bulky with tags, but they can
really do a document proud, as in the case with the Introduction to
Linux Hands-on Guide.
> Thanks. :) I'm working on this one right now:
> http://linuxdoc.com/howto/emacs_sgml/index.lxp?lxpwrap=x77%2ehtm
> (that page only, really)
>
> and following the structure of this:
> http://cvsview.tldp.org/index.cgi/*checkout*/LDP/howto/docbook/RedHat-CD-HOWTO/RedHat-CD-HOWTO.sgml?rev=1.4&content-type=text/plain
At a glance, the first link gives a great jump start to starting a basic
SGML document, and the second is an excellent example of clean and
efficient usage. Thanks for sharing!
> I installed all the emacs/sgml stuff but I'm butterfingers when it comes
> to emacs. I've flipped back to vim and am just going through trying to
> figure out what should be what. I've converted the easy stuff: title,
> emphasis para, ulink, screen; added sections (sect1, sect2); and added
> the author notes at the beginning of the file. Tomorrow will be unordered
> lists, definition lists, kbd and var.
Question...have you tried XEmacs instead? And do you have the PSGML
plugin for it? You'll know if you do because loading any file with an
xml or sgml extension will provide you with additional menus to work
from, all easily drop down. You can "set the face" of the markup tags
so that they're bold, you can parse and validate, and find the next
valid tag from wherever you are. In my RH8 everything was all ready to
go.
Vim is something I use when I'm on a remote machine, but locally, the
Emacs with the PSGML really does the markup a service.
> The syntax coloring in vim tells me whether or not the tag is valid.
> (Yellow = yes, blue = no)
Emacs/XEmacs, with the PSGML has a "Move to next trouble spot" menu item
that does pretty much the same thing to the entire doc. I've never
really paid it much attention in Vim, but I will next time I'm using it!
> I'll try to revise the text as I go to take out the text references to a
> "side bar" -- I'm pretty sure I can still link internally within the
> document, but I'm too tired to remember what the element is right now.
Once you get past the big stuff in your document, such as formatting
chapters and sections, then move down to the smaller things like maybe
images and tables, you can fine tune even more. I usually keep the
DocBook guide up with the list of tags so that I make use of as many as
possible. No need to do it to death, but it can down the road make
things like indexing *much* easier!
As to the side bar, there are ways of setting off text in DocBook as
well. Of course though, you are referring to the actual words "side
bar." Just thought I'd remind you of "Notes", "Warnings", and other
admonitions that you can use in much the same way, if you haven't
already run across them. They come with graphics too - and that is
always nice on the eyes.
I'm always here, just give me a holler if you have a question!
Tab
--
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
