discuss: Thread: SGML / XML

I think it's time to explicitly request that people NOT use SGML
shortcuts, eg:

* please don't use </> - spell the ending tag out correctly

Besides, it's good form. When you get nsgmls spitting out 800 lines of
errors, you don't have to wander around trying to work out which </>
belongs to what starting tag....

What do we think?

DSL

-- 
Domine O venite O sacramentum eo deo
Domine O venite O sacramentum eo deo
Omnem crede diem tibi diluxisse supremum.
Sacramentum eo deo

On 06 Mar 2001 21:37:16 +1030, David Lloyd wrote:
> 
> I think it's time to explicitly request that people NOT use SGML
> shortcuts, eg:
> 
> * please don't use </> - spell the ending tag out correctly
> 
> Besides, it's good form. When you get nsgmls spitting out 800 lines of
> errors, you don't have to wander around trying to work out which </>
> belongs to what starting tag....
> 
> What do we think?

I've been saying this for a very long time, but there are a few voices
left that are opposed to looking at tomorrow's technologies before
they've taken over the market completely.  A decent XML editor removes
almost all of the burden of markup, and good markup is much easier to
read than poor markup.

    Greg

> On 06 Mar 2001 21:37:16 +1030, David Lloyd wrote:
> > 
> > I think it's time to explicitly request that people NOT use SGML
> > shortcuts, eg:

I don't agree.  Especially with linuxdoc where no tags are used for
paragraphs.  

On Tue, Mar 06, 2001 at 07:53:19AM -0800, Gregory Leblanc wrote:
> I've been saying this for a very long time, but there are a few voices
> left that are opposed to looking at tomorrow's technologies before
> they've taken over the market completely.  A decent XML editor removes
> almost all of the burden of markup, and good markup is much easier to
> read than poor markup.

That's fine if one is proficient at using an XML editor (and also has
such an editor).  But someone who writes a short HOWTO (perhaps only a
few pages) will not want to undertake the burden of learning the use
of a new editor.  Thus to minimize the burden of markup (in such a
case where one is entering the tags manually) one should use the
simplest markup with simple shortcuts.

			David Lawyer

>
>I don't agree.  Especially with linuxdoc where no tags are used for
>paragraphs.

But we aren't supposed to use Linuxdoc for new Articles.

>
>On Tue, Mar 06, 2001 at 07:53:19AM -0800, Gregory Leblanc wrote:
>> I've been saying this for a very long time, but there are a few voices
>> left that are opposed to looking at tomorrow's technologies before
>> they've taken over the market completely.  A decent XML editor removes
>> almost all of the burden of markup, and good markup is much easier to
>> read than poor markup.
>
>That's fine if one is proficient at using an XML editor (and also has
>such an editor).  But someone who writes a short HOWTO (perhaps only a
>few pages) will not want to undertake the burden of learning the use
>of a new editor.  Thus to minimize the burden of markup (in such a
>case where one is entering the tags manually) one should use the
>simplest markup with simple shortcuts.
>
>			David Lawyer
>
>_________________________
>http://list.linuxdoc.org/
>

-- 
--
<COMPANY>CommandPrompt	- http://www.commandprompt.com	</COMPANY>
<PROJECT>OpenDocs, LLC.	- http://www.opendocs.org	</PROJECT>
<PROJECT>LinuxPorts 	- http://www.linuxports.com     </PROJECT>
<WEBMASTER>LDP		- http://www.linuxdoc.org	</WEBMASTER>
--
Instead of asking why a piece of software is using "1970s technology,"
start asking why software is ignoring 30 years of accumulated wisdom.
--

On Mar 7, 12:17pm, Poet/Joshua Drake wrote:
> Subject: Re: SGML / XML
> >
> >I don't agree.  Especially with linuxdoc where no tags are used for
> >paragraphs.
>
> But we aren't supposed to use Linuxdoc for new Articles.

If the author so chooses, Linuxdoc is fine/accepted. I try to
gently push them in the direction of DocBook, but it's certainly
not a requirement (or a "barrier to acceptance" as the case may be),
nor do I believe it ever should be.

r,
Ferg

On Wed, Mar 07, 2001 at 03:51:26PM -0500, Greg Ferguson wrote:
> On Mar 7, 12:17pm, Poet/Joshua Drake wrote:
> > Subject: Re: SGML / XML
> > >
> > >I don't agree.  Especially with linuxdoc where no tags are used for
> > >paragraphs.
> >
> > But we aren't supposed to use Linuxdoc for new Articles.
> 
> If the author so chooses, Linuxdoc is fine/accepted. I try to
> gently push them in the direction of DocBook, but it's certainly
> not a requirement (or a "barrier to acceptance" as the case may be),
> nor do I believe it ever should be.

Yes, and experience has shown that we don't *need* to get fascist
about this issue. Since we started requesting DocBook, almost all new
documents have been received in DocBook, and many existing docs have
been converted. No need to make it an absolute.

-- 
Dr. David C. Merrill                     http://www.lupercalia.net
Linux Documentation Project                   ####@####.####
Collection Editor & Coordinator            http://www.linuxdoc.org
                                       Finger me for my public key

He that is giddy thinks the world turns round.
		-- William Shakespeare, "The Taming of the Shrew"

>not a requirement (or a "barrier to acceptance" as the case may be),
>nor do I believe it ever should be.

It absolutely should be. It is imperative to the growth of any
organization to have certain standards in place. Debian, Gnome, KDE all
have specific standards for code and documentation.

W

>
>r,
>Ferg
>

-- 
--
<COMPANY>CommandPrompt	- http://www.commandprompt.com	</COMPANY>
<PROJECT>OpenDocs, LLC.	- http://www.opendocs.org	</PROJECT>
<PROJECT>LinuxPorts 	- http://www.linuxports.com     </PROJECT>
<WEBMASTER>LDP		- http://www.linuxdoc.org	</WEBMASTER>
--
Instead of asking why a piece of software is using "1970s technology,"
start asking why software is ignoring 30 years of accumulated wisdom.
--

On Mar 7,  3:06pm, Poet/Joshua Drake wrote:
> Subject: Re: SGML / XML
> >not a requirement (or a "barrier to acceptance" as the case may be),
> >nor do I believe it ever should be.
>
> It absolutely should be. It is imperative to the growth of any
> organization to have certain standards in place. Debian, Gnome, KDE all
> have specific standards for code and documentation.

Absolutely (wrt the standards remark); and we do have standards:

- documented in the LDP Author Guide
- exhibited by the available SGML documents templates,
- and as noted by:

  "The LDP officially supports:

       SGML - Linuxdoc, DocBook v3.x, DocBook v4.x
       XML  - DocBook v4.1.2"

r,
Ferg

David et al:

> > On 06 Mar 2001 21:37:16 +1030, David Lloyd wrote:
> > >
> > > I think it's time to explicitly request that people NOT use SGML
> > > shortcuts, eg:
> 
> I don't agree.  Especially with linuxdoc where no tags are used for
> paragraphs.

Would you accept a rewrite that says something like:

"If you write a document using DocBook, please try to:

* end all closed tags with their full ending tags:
 eg: <para>an inane paragraph</para> INSTEAD OF
     <para>an inane paragraph</>

* use all lower-case for tag names:
 eg: <title>new howto</title> INSTEAD OF
     <Title>new howto</Title>

* quote ALL attributes:
 eg: <xref linkend="my.link">
"

This isn't bullying, telling people to use DocBook and such. 

> That's fine if one is proficient at using an XML editor (and also has
> such an editor).  But someone who writes a short HOWTO (perhaps only a
> few pages) will not want to undertake the burden of learning the use
> of a new editor.  Thus to minimize the burden of markup (in such a
> case where one is entering the tags manually) one should use the
> simplest markup with simple shortcuts.

But should DocBook go XML only - which I sense is where it is heading -
rendering DocBook SGML with abbreviations can be quite a task. There are
"normalisation" programs (sgmlnorm I think is the name of one) the ones
I've seen mangle the format of the document produced. That is to say,
they take a nicely indented SGML documented and make some dog's dinner
that is good XML but source code unreadable.

If someone is writing a short HOWTO, they could ask someone else to
write it up in properly formatted DocBook (or LinuxDoc) thereby
releasing them from any markup burden at all...

DSL
-- 
Domine O venite O sacramentum eo deo
Domine O venite O sacramentum eo deo
Omnem crede diem tibi diluxisse supremum.
Sacramentum eo deo

On Thu, Mar 08, 2001 at 10:16:00AM +1030, David Lloyd wrote:
> > That's fine if one is proficient at using an XML editor (and also has
> > such an editor).  But someone who writes a short HOWTO (perhaps only a
> > few pages) will not want to undertake the burden of learning the use
> > of a new editor.  Thus to minimize the burden of markup (in such a
> > case where one is entering the tags manually) one should use the
> > simplest markup with simple shortcuts.
> 
> But should DocBook go XML only - which I sense is where it is heading -

DocBook 5.0 will be XML only (sort of).

See http://www.oasis-open.org/docbook/meetings/min20001207.html under
"Discuss plans for DocBook 5.0"

> rendering DocBook SGML with abbreviations can be quite a task. There are
> "normalisation" programs (sgmlnorm I think is the name of one) the ones
> I've seen mangle the format of the document produced. That is to say,
> they take a nicely indented SGML documented and make some dog's dinner
> that is good XML but source code unreadable.

We badly need a generic version of Dave Ragget's tidy program.

Oh yes, "Hi Folks".

N
-- 
FreeBSD: The Power to Serve             http://www.freebsd.org/
FreeBSD Documentation Project           http://www.freebsd.org/docproj/

          --- 15B8 3FFC DDB4 34B0 AA5F  94B7 93A8 0764 2C37 E375 ---