RE: Updates/changes to the HOWTO template.

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

> -----Original Message-----
> From: Greg Ferguson [mailto:gferg@hoop.timonium.sgi.com]
> Sent: Thursday, June 01, 2000 1:31 PM
> To: Ldp Discuss List (E-mail); Ldp Docbook List (E-mail); Gregory
> Leblanc
> Subject: Re: Updates/changes to the HOWTO template.
> 
> On May 31,  2:45pm, Gregory Leblanc wrote:
> > Subject: Updates/changes to the HOWTO template.
> >
> > I've gone and scratched a few more things out here, mostly they're
> > changes to the markup, but there are a few other changes as well.
> > I changed a couple of RAID things, since it's not called 'md'
> > anymore.  Not sure if I made any other major changes.
> > 	Greg
> 
> I've cleaned up the line spacing to make this more readable,
> put in some additional conventions that seem to work quite well
> (such as a <revhistory>), added more examples (for <mediaobject>
> and <orderedlist>), and also used <sect1> and <sect2> for more
> clarity.
> 
> The SGML file is :
> 
>   http://metalab.unc.edu/gferg/ldp/template/big-howto-template.sgml

ok, I've got some comments, as always.  I've made a few grammatical changes
to the copy that I've got here, but I won't be sending those until I get
back home (I'm on the road until Thursday evening).  The version that I'm
going from is the one listed above, so "you" is a general term, don't take
it too personally.

Just before the start of each section, you've placed something that reads
like "<!-- S e c t i o n2 -->".  This SEEMS like a good idea, but placing it
in a comment, and spelling out the entire word leads to confusion, in my
mind.  Instead of thinking "this is a level 2 section," I think "this is the
section numbered 2".  Obviously, that's not what we want.  If you want to
keep those comments as navigation aids, I'd suggest something more like what
Emacs displays at C-c C-c; "in SECT2 in SECT1 in ARTICLE", although that
isn't necessarily great either.  Hmm, maybe "this is the start of sect2,
inside of sect1, inside of ARTICLE".  Maybe just get rid of them, I'm not
sure.  

I don't have any web access right now, so I can't check this out, I'd
appreciate it if somebody could take a look.  I'm curious as to whether the
<author> tag is intended only for the author(s) of this document (meaning,
in this case, the people who wrote the template), or for author(s) of any
work that you cite.  If it's intended for any time that you'd like to
identify authors as such, then in the paragraph about "DocBook: The
Definitive Guide", Norm Walsh and Leonard Muellner should be marked as
<author> and not as <emphasis>.  Again, not sure what the intent of the
<author> tag is, so I'd appreciate it if somebody could take a look.

I think we should make better use of the "id" attribute, especially when
starting new sections.  I've added id's to the copyright and disclaimer
sections, among others.

What's the general policy on <email>?  I've been confused ever since I tried
to make an author have an email address in one of my documents, and couldn't
make it work.  Do we need <address>, or is that redundant?

How should linking between HOWTOs be accomplished?  In the reading plan
example, "newbies" are recommended to read all of the other disk related
HOWTOs.  If I were a newbie, I wouldn't know what to read.

Just as an informational thing, is vger still that overloaded?  I know that
it's running on an SS10 now, rather than the old, slow IPX.  Email through
the lists that I read there seems to be plenty fast, especially since the
CVS repository is gone from there.

In the section about other HOWTOs, is Metalab too generic of a term?  There
are dozens of SunSites around the nation, but is it obvious that we're
talking about the MetaLab machine hosted by the University of North
Carolina?

I seem to recall someone mentioning a site that tried to keep an up-to-date
list of all of the Linux Users Groups.  It would be nice to include a link
to this site in the help section.

That's all I've got for the time being, so I'm going to mail this off.  I'll
be quite slow at responding to email until Thursday or Friday, so please be
patient with me.  Thanks!
	Greg


--  
To UNSUBSCRIBE, email to ldp-docbook-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org