Re: Rep:Re: Permission to submit HOWTO

[Joe Cooper <joe@swelltech.com>]

Gary Preckshot wrote:
> 
> Joe Cooper wrote:
> >
> > Though I am loathe to feed the troll, I can't let it go unanswered.
> 
> You never met a nicer, more constructive troll. I
> don't flame people, and my post was accurate.

Perhaps.  The original post still seemed rather inflammatory (as was my
reply).

> > Gary Preckshot wrote:
> >
> > No vagueness here Gary.  DocBook is the preferred markup of the LDP.
> > Because it is a volunteer organization, other formats may be accepted.
> > LinuxDoc will be accepted for historical reasons.
> 
> That isn't clear from the H-H. For example,
> LinuxDos is given a whole section, while DocBook
> has nothing.

I don't know what H-H you're reading but the one I'm looking at is
exclusively made up of DocBook information.

> > > 2) it would be nice if some volunteers did markup
> > > for new authors, but there's no roster of
> > > volunteers.
> >
> > Are you volunteering?  How about you start keeping the list.
> 
> It's something the LDP servers should support.

Ok.  I agree.  Which should it be:

1. A button for authors to click, saying "Please SGMLize my HOWTO,
here's my email address" which puts their name on a list.

2. A button for volunteer SGML'ers to click, saying "I am willing to
DocBookize HOWTO's for any comers.  Here is my email address."

3. Or something more complicated that keeps up with who is on what
project and how far along it is.

What do we need in the script and what will the website maintainers
accept and put online?  Can we start from a currently available
guestbook/bulletin board/workgroup/whatever script?  Anyone have such a
script that they'd be willing to modify for this purpose?  Or send it my
way and I'll look into what would need to be changed, and I'll have a go
at it.
 
> First off, I never proposed that people buy
> WP/Win, I just showed it worked a lot better than
> any of you suspected. I acknowledged a post that
> pointed out that emacs with psgml worked ok.
> Third, I never made an ad homonym attack on
> anybody as you just did on me.

Nothing ad hominem about it.  You've made it clear that you have
animosity towards people doing SGML by hand.  I'm not sure why, but that
is clearly your attitude.  I'm just pointing it out and hoping you'll
drop it.

> I sent an entire template called example.sgm to
> Mark as part of the H-H markup I sent him. What's
> wrong with Stein's template: 1) it doesn't
> demonstrate the use of many of the 300 tags in
> DocBook. To be fair, neither does example.sgm.
> However, I think David Merrill or somebody else
> has undertaken to extend example.sgm. That's fine
> with me. 

Good job.  I haven't looked at your example, but I imagine it will be
quite helpful to have open in the window next to your editing window so
you can get a nice overall view of things.

As for complaint #1...We aren't USING all 300 tags, and it would be
stupid to try to use 300 tags in the template.  We need a subset, and
the template marks out that subset pretty well.  Maybe a couple more
need to be added along the way as special cases arise.  I think it's
great that you're stirring things up in this regard, but sometimes it's
nice to stop finding fault, and say, "Hey that works pretty well. 
Though maybe not exactly the way I would have done it, I think we can
start working on something else now."

> 2) There's a lot of extraneous text in
> the template, detracting from its use as a working
> skeleton. 

One could argue that the extraneous text is needed to make it clear what
each section and tag is really about.  But I agree that it could
probably stand to be shrunken somewhat.

> 3) There are various versions floating
> around. New submissions should be in DocBook 3.1.
> LinuxDoc versions just confuse matters. To quote
> yourself, "Get over LinuxDoc, Joe."

Ok.  But are people really confused at this point about which is which? 
I guess if they are, then the LinuxDoc template should be moved to an
archive merely for posterity.
 
> > Damn those individualists.  Always ruining our good time.  Gary, a lot
> > of people do not want to use WordPerfect for Windows to write their
> > Howto's.  Get over it already!  No one is trying to tell you not to use
> > WP/Win...How about leaving us vi users in peace and stop acting like
> > we're doing harm to the LDP by using command line tools.
> 
> Emacs runs on all sorts of platforms and can be
> used on Linux. From what at least one poster has
> said, it's very good. LDP is being held back by
> rugged individualists who are determined to write
> in raw SGML no matter what the cost. The cost is
> high. There's nothing they can't do with an
> SGML-aware editor they can't do with vi except
> make it hard for LDP to do other things it wants
> to do. Specifically, by including "inventive"
> constructions, they obfuscate or make it more
> difficult to do search engines.

Again, Gary, you are imagining a scenario that just does not exist.  The
policy has been agreed upon.  No minimized tags.  There is no reason
handwritten SGML can't adhere strictly to the letter and intent of the
DocBook/LDP guidelines.  You're allowing your own prejudices regarding
standard Unix tools to cloud your vision.
 
> DocBook is complicated enough without bringing yet
> another source into the discussion. DocBook is
> intended to facilitate the writing of books and
> other literature, and quoting the Definitive Guide
> completely ignores the fact the LDP uses a subset.
> What's needed is not quotations from a bible, but
> hard facts about what LDP wants to see. For
> example, you're using "article" not "book", you
> don't use "chapter," Mark has just deprecated
> "Graphic," and there are sundry other tags either
> not being used or being used strangely.

I brought up DocBook:TDG because it is an excellent reference and one of
it's points was that minimized markup can be expanded easily with
sgmlnorm.  You stated your anger towards people who handwrite SGML and I
told you of an easy way for even laxy handwriters to produce code to the
letter and intent of the LDP policy.  That solution has not been heeded
by you so far...but I offered. 

Regardless of that, there is no reason not to recommend people take a
gander at TDG.  It is a good book.  DocBook is not a confusing markup
language, and there is no reason someone can't gain valuable knowledge
and understanding from a few minutes of browsing through relevent
sections of TDG while composing a HOWTO.

Finally, when the subset has been agreed upon, we should codify it and
put it on the website in an easy to find spot.  Let's start talking
about that subset.  I haven't seen a thread on it yet...shall we start
one?  Perhaps we should begin by stripping all tags from the template
(and example.sgm?) and annotate them?  Is that a good start for defining
our subset?

> I could easily write an awk script for finding
> objects in DocBook SGML, but to what purpose? LDP
> has a de facto database of documents in SGML. Each
<...much verbiage removed...>
> definitions. Of course, you can do full text
> search, but you could do that on any text format.

Ok.  We all know that.  Now let's work on doing something about it.

> You suggest fixing it. Ok, here's the fix: 1)
> Don't accept anything but DocBook SGML, with no
> minimization. 

This is already the agreed upon policy.

> 2) Define a set of required tags
> that will be used for search. 

Ok.  Do you want to start the new thread on this, or shall I?  Where do
we start...with index tags? section tags? something else?  What are the
good tags to use for intelligent context sensitive searches?  

Or are we coming from the wrong direction...should the search tool know
about most of the relevant tags (i.e. "example" tags, "code snippet"
tags, etc.) and allow a search based on any of those criteria?

> 3) Put together an
> on-line thesaurus of keywords. 

Ok, I'm seen a Glossary suggested, but no thesaurus suggestion so far. 
Why a thesaurus?

Let's get those search terms settled on and we'll make sure that every
HOWTO that has a glossary uses those tags for glossary items...so that a
LDP-wide meta-dictionary can be constructed.

Good idea Gary.  Let's get on it.  Sounds like another thread to me.

4) The question of
> referring to other howtos is intimately connected
> with the search and display problems. 

Yep.  Gotta figure out what to do directory wise.  Already a thread
going on about this and internal referencing.

> 5) Define
> (E.g. select from the DocBook DTD and publish)
> indexing tags to allow for "go to" display of
> cross-referenced or searched documents. At the
> moment, HTML looks like the only format amenable
> to this function. 

I don't get what you mean?  HTML is the only HyperText capable mode
we've got (other than the very limited PDF), true.  But I think that's
really where things like an intelligent search needs to happen anyway. 
Our only problem in this regard is making the search on the SGML using
intelligent tag reading and then placing the reader into the correct
spot in the HTML online and making it seamless.  

I don't have the perl/db abilities to make this kind of thing happen, so
I'll leave it to others.  I'll personally throw $50.00 into a pot
towards encouraging a programmer out there to make it happen.  If anyone
else is interested, I'll start a pool on one of the various programmer
exchange websites.

> 6} Identify a set of tools that
> will produce SGML to the requirements stated
> above. 

vi and a hand or two can do it.  ;-)

> We'll need a scanner that parses incoming
> SGML and annotates it for rugged individualists so
> their submissions can be corrected to meet
> requirements. There isn't any reason this can't be
> made available to anyone who wants it, and there's
> no reason it can't be something as simple and
> understandable as an awk script.

Get real Gary.  An automatic SGML tool can be used to generate
deprecated tags, extraneous tags (that aren't in the LDP subset) and
overall ugly code, just as much as a rugged individualists' vi can.  Get
off the GUI high horse Gary.

Now, if you'd like for there to be a script to correct everyone's
mistakes, I won't try to stop you...But really, I think you're way too
worried about rabid vi users bringing anarchy to the LDP.  Brother, I
gotta tell you, the LDP was built with vi and Emacs (with no SGML mode,
in the beginning) long before either of us were around.
 
> > > Beyond that, everything is clear-cut. Welcome to
> > > LDP.
> >
> > ...And don't feed to trolls.  Doh!  I guess I already did that.
> 
> Feed a troll and you either end up as part of the
> meal, or you get more than you expected.

And sometimes poking a troll gets him to say something useful.  ;-)

Just poking at you Gary.  Glad to see you've got some ideas behind the
complaints.
 
> > Sorry, Gary, to be so critical...but I'm getting the distinct impression
> > that complaining is your primary function around here.  What was it you
> > were working on again?
> 
> I don't bitch without offering constructive
> solutions. Whether you consider them or not is up
> to you. For the record, some people seem more
> concerned with the smoothness of their feathers
> than what I have to say.

In this post you're offering constructive solutions.  I still hold that
your first post was very much of the troll nature.  Perhaps my reply was
overly critical, but Gary, you just bring it out of me!  ;-)

And that's all I've got to say about that.
                                 -- 
                    Joe Cooper <joe@swelltech.com>
                Affordable Web Caching Proxy Appliances
                       http://www.swelltech.com


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