[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: Authorship

> -----Original Message-----
> From: Anthony E. Greene []
> Sent: Wednesday, May 31, 2000 1:34 AM
> To: LDP
> Subject: RE: Authorship
> At 21:40 2000-05-30 -0700, Gregory Leblanc wrote:
> >I'd like to see us adopt some more formal conventions, and 
> have them better
> >stated.  We could even provide a short section that people 
> could just block
> >include into their HOWTOs that shows the general conventions.
> As a potential HOWTO author, I like this idea.
> >> >I've read the HOWTO-HOWTO and the section on style is very brief.
> >> Is there
> >> more guidance on how a HOWTO should be structured?
> [snip]
> >Was the question about Markup style, or about writing style?  They're
> >completely different, and both completely undefined.  
> This was my question. It was about markup style and standard 
> information to
> include. A section on conventions is a good example of what I 
> mean. The
> HOWTOs are pretty easy to read, but having markup standards 
> and standard
> sections that may be copied in or included as an entity would 
> be a step in
> the right direction. The LDP docs would then be more consistent and
> therefore a little easier to use. If done well, it would be 
> possible to
> build a database of some of the information (then again 
> there's always grep).

I think that many of the Linuxdoc documents are good examples, and there's
not a lot of flexibility there.  I'll have to take a look at the DocBook
ones, but I don't personally like the markup turned out by either LyX or
Word Perfect.  Give me Emacs and I can get stuff done.  8^)  Even the
template that I converted from Stein's Linuxdoc version has only about 65%
of the markup that it could/should.  

> >I think it would be nice to use Stein's template as THE 
> template.  There are
> >now DocBook and Linuxdoc versions (as of earlier today I 
> created a DocBook
> >version).  I disagree with some of the markup, and more of 
> the content, but
> >I'll get to those soon.  
> This is something I'm interested in. After reading several 
> HOWTOs, I really
> think they're good, but could stand some standardization. 
> Templates would
> help this and help potential authors get started.

Yeah, another note on templates.  For some reason, some people believe that
"the template is right" when the find templates.  The template is nothing
more than a good example.  There are things that are probably wrong in
there, and there are certainly different ways of doing things than what's in
the template.  Perhaps I'll dig into the template a bit more, and see what I
can do with the DocBook version.

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