docbook: Thread: Re: How to create a HOWTO on Red Hat Linux 9?

At 17:23 10/19/2003, David Lloyd wrote:

>It's not a linuxdoc format. The Doctype declaration should be obvious that
>it's DocBook V3.1.
>
>Try:
>
>  docbook2pdf sourcefile.sgml

Thanks, Dan. Keep in mind that I've never done this before, so "obvious" 
things do not yet jump out at me.

The command suggested worked and generated a functional HTML page, albeit 
with some weird things like putting "<P" on one line and the closing ">" on 
the other line (and the same for most every other tag). HTML Tidy generated 
63 warnings on the generated HTML and fixed the tags to "<P>", but both the 
original and the tidied version showed up in a browser visibly.

However, docbook2html also generated a bunch of errors, attached here, and 
mostly about some elements like "SECT2" not being allowed by the document 
type. I'm using Stein Gjoen's "big-howto-template.sgml" and have not 
changed anything substantive in the tags (including the DOCTYPE on the 
first line), so I don't know what it's complaining about.

Should I somehow switch this thing to Linuxdoc, or where can I find a 
Docbook quick-reference guide or tutorial that will get me off the ground? 
Between Linuxdoc and Docbook, is there a "better" choice for me? For 
documents which could eventually be submitted to the LDP for inclusion? For 
Linux documentation in general? I want to write nice, clean, clear, 
well-documented code with no bugs... but I don't have much (or any) real 
experience at this and I guess I need a little primer or help to get started.

Comments on the errors? Choice of Linuxdoc/Docbook? Anything?

Thanks,


-- 
Rodolfo J. Paiz
####@####.####

At 01:11 10/20/2003, David Lloyd wrote:
> > Thanks, Dan. Keep in mind that I've never done this before, so "obvious"
> > things do not yet jump out at me.
>
>Who is Dan?

Well, if you made the obvious comment, then clearly my brain was misfiring 
and I misread the name. Oops... sorry! <smile>

>Yes, I know. The translator it uses makes very, very weird HTML. I
>wouldn't be too horrified by it.

I will continue to run HTML Tidy on it, but it doesn't seem right that my 
code should be less attractive and organized than machine-generated code, 
don't you think? Is there any way to fix this?

> > However, docbook2html also generated a bunch of errors, attached here
>
>They are? I don't seem to have them :(

My bad... must not have attached the file. In any case, I have made some 
improvements but apparently there are lots of tag issues with my "BR" tags 
in particular, albeit with some others as well. I wsa told to use BR tags 
alone (not in pairs) anytime I wanted a newline or line break, but not a 
full paragraph tag. Is there something wrong with this? Of course, that's 
not the only error; file attached (for sure).

I have also changed the first line (DOCTYPE) to say "DocBook V4.2" by hand; 
I assume that doing so will not break anything.

>Also there's The Definitive Guide to Docbook online at:
>
>  http://www.docbook.org/
>
>The book is readable online but also buyable as an O'Reilly published
>book.

Always happy to support O'Reilly, but I'm outside the USA and will buy the 
book when I get a chance. For now, online is all I got.

> > Between Linuxdoc and Docbook, is there a "better" choice for me?
>
>That's a religious war. DocBook has a richer, but more stringent syntax
>than Linuxdoc.\

Docbook it is, then. I don't mind more stringent.

> > For Linux documentation in general?
>
>In general? That really does depend.

My apologies. I meant "for documentation I will write, to be published in 
TXT, HTML, PDF, SGML/XML, about Linux-related subjects". Again, DocBook 
seems to be a good choice. I'll move to XML as soon as the tools seem to 
have matured a bit... my first attempt to write this HOWTO was in XML and I 
got absolutely nowhere, so reverted back to SGML.


-- 
Rodolfo J. Paiz
####@####.####

onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:7:10:E: element "ARTHEADER" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:117:33:E: element "STRONG" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:122:33:E: element "STRONG" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:128:28:E: element "STRONG" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:323:40:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:324:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:331:30:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:332:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:333:44:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:334:63:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:335:77:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:336:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:341:18:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:342:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:345:19:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:346:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:346:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:345:15: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:342:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:341:14: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:336:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:335:73: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:334:59: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:333:40: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:332:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:352:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:331:26: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:356:56:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:357:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:358:65:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:359:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:363:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:359:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:363:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:358:61: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:363:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:357:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:363:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:356:52: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:369:32:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:370:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:379:18:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:380:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:387:38:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:388:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:389:19:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:390:80:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:397:38:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:398:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:400:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:398:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:400:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:397:34: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:404:45:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:405:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:407:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:405:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:407:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:404:41: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:414:19:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:415:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:416:49:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:417:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:420:73:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:421:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:422:31:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:423:31:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:424:35:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:425:84:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:426:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:429:34:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:430:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:431:70:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:432:33:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:433:22:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:434:18:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:435:17:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:436:18:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:437:18:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:438:18:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:439:51:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:440:18:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:441:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:441:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:440:14: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:439:47: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:438:14: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:437:14: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:436:14: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:435:13: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:434:14: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:433:18: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:432:29: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:431:66: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:430:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:429:30: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:426:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:425:80: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:423:27: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:422:27: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:421:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:420:69: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:417:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:416:45: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:415:6: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:447:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:414:15: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:470:70:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:471:10:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:472:20:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:473:87:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:474:80:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:475:68:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:476:13:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:477:64:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:478:13:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:479:52:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:480:55:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:481:25:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:482:47:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:483:35:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:484:37:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:485:39:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:486:43:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:487:48:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:488:53:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:489:63:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:490:49:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:491:62:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:492:49:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:493:61:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:494:83:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:495:44:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:496:63:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:497:77:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:498:49:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:499:51:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:500:45:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:501:46:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:502:38:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:503:44:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:504:47:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:505:70:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:506:74:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:507:30:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:508:39:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:509:33:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:510:33:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:511:68:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:512:63:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:513:44:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:514:33:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:515:74:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:516:75:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:517:72:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:518:37:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:519:66:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:520:68:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:521:79:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:522:34:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:523:77:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:524:82:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:525:84:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:526:45:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:527:55:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:528:45:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:529:25:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:530:29:E: element "BR" undefined
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:530:25: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:529:21: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:528:41: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:527:51: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:526:41: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:525:80: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:524:78: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:523:73: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:522:30: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:521:75: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:520:64: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:519:62: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:518:33: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:517:68: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:516:71: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:515:70: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:514:29: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:513:40: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:512:59: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:508:35: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:507:26: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:506:70: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:496:59: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:495:40: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:494:79: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:493:57: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:481:21: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:480:51: start tag was here
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:532:12:E: end tag for "BR" omitted, but OMITTAG NO was specified
onsgmls:Sendmail-SMTP-AUTH-HOWTO.sgml:479:48: start tag was here

On Sun, 2003-10-19 at 18:54, Rodolfo J. Paiz wrote:
> Should I somehow switch this thing to Linuxdoc, or where can I find a 
> Docbook quick-reference guide or tutorial that will get me off the ground? 
> Between Linuxdoc and Docbook, is there a "better" choice for me? For 
> documents which could eventually be submitted to the LDP for inclusion? For 
> Linux documentation in general? I want to write nice, clean, clear, 
> well-documented code with no bugs... but I don't have much (or any) real 
> experience at this and I guess I need a little primer or help to get started.
> 
> Comments on the errors? Choice of Linuxdoc/Docbook? Anything?

Hi Rodolfo,

I know how frustrating it can be to figure all this out.  Let me start
by saying there are some widely differing opinions on which flavor of
markup to use.  Linuxdoc has benefits in that it's easy to learn,
doesn't require strict usage (such as closing tags) that DocBook does. 
On the other hand, DocBook has a larger variety of tags to choose from
and inserts images well.  Many say DocBook is bloated with tags, but I
consider it variety.

THE definitive guide on DocBook is at:
http://www.docbook.org/tdg/en/html/docbook.html

This lists all the tags and their usage.  Now when I was new at this,
that list was all fine and dandy, but I was still a little lost.  I run
RH8, and the authoring tools were already installed.  Since you're
running RH9, the tools are most definitely there.  Which means that you
have Emacs and Xemacs, and you probably have the PSGML plugin installed
as well.  The Xemacs editor is the one I like to use, and with the psgml
plugin, you get additional menus to work with the markup.  It can
highlight them, and though it has a validator (which I find to be
gimpy), there's this nifty menu command called "Find next trouble spot,"
which automatically moves to an error in markup syntax.  You can even
find out which tags are valid from anywhere in your document with one
drop-down menu command (list valid tags).

Now, all of this of course means DocBook.  But there are still 2 flavors
of DocBook to consider: SGML and XML.  I prefer XML, because it's
everything that SGML is, but with one extra line at the top.  You can
take a look at the source for any recent HOWTO written in XML and see
how simple it is.  XML is supposedly the hot thing right now, which is
why I use it instead.  The Openjade tools are great for processing with
dsl files, and the xslt tools are good for using xsl files (those are
the stylesheets - dsl for SGML, and xsl for XML).

The LDP supports all of them: Linuxdoc, DocBook SGML and XML.  I like to
see new docs come in as XML, and some of us are even willing to
volunteer our time to help you convert your text to XML if you need
help, but it sounds like you want to give this a try on your own, and I
think that's a good idea.  Then it will take out the mystery for you. 
If you don't think you need everything DocBook offers, we have
documentation at the LDP for working in Linuxdoc too (see link below).

The LDP has many guides on the subject of authoring tools, if I haven't
already got that covered for you.  Try this link for a full list of what
we've got:  http://www.tldp.org/HOWTO/HOWTO-INDEX/misc.html#MISCAUTHOR

I'll leave you with all that to chew on, and if you have any other
questions, feel free to contact me off-list.  

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)

At 15:54 10/20/2003, David Lloyd wrote:
>What are you using the <BR> for? I didn't think that it existed in DocBook
>(or LinuxDoc for that matter).

<grin> How would I know?

I'm using <br> like I use "Shift-Enter" in my word processor: start a new 
line, but do not consider this a new paragraph. Is there such a thing? If, 
for instance, I am listing a bunch of things and I want each on its own 
line, but I don't want a space inserted between them as it is for 
paragraphs, what tag would I use?

And since we're on specific tags, one more: in several cases I am showing 
the user what commands to type and the output of commands on screen. Is 
there a tag I can use that will put all output in constant-width font like 
Courier, to simulate text-based screen output?

>The best tip:
>
>  1 DON'T use SGML short cuts
>  2 Always close ALL tags

Will keep those in mind. I did see the possibility of the <tag>stuff</> 
thing, but it looked sloppy and unclear to me so I had already decided 
never to use that. I didn't even know you could do the <tag/> thing. I'll 
stay away from it then.


-- 
Rodolfo J. Paiz
####@####.####

This email sent to both the "discuss" and "docbook" lists deliberately.

-----------------

For the discuss list: kindly review and offer feedback or comments on the 
brief document located at

http://apollo.simpaticus.com/linux/howto/html-single/Sendmail-SMTP-AUTH-HOWTO.html

-----------------

For the docbook list, I have a couple of questions:

         1. Where I present something the user should type in, I have used 
the COMPUTEROUTPUT tag to show the shell prompt so it's not displayed in 
bold, and then the USERINPUT tag to show what the user actually types. 
However, it is then showing the output on two separate lines; is there a 
way I can tell it not to do this?

         2. There is a space between a paragraph and the gray area which 
represents a SCREEN tag, but there is no space between the gray and the 
next paragraph. How should I tag this so the spacing is symmetrical, before 
and after?

         3. There is always two or three lines of blank gray-shaded space 
in a SCREEN tag. It starts out with text right on the first line, but 
leaves blank gray after. Can I avoid this?

         4. If I try to create multiple HTML pages instead of just one, the 
filenames are "t1.html" and "x76.html" which seems very odd to me. Is there 
no way to suggest "howto-1.html" and "howto-2.html" names? I remember the 
old sgml-tools used to name them this way, and it seemed a much more 
intuitive method to me.

         5. The "onsgmls" parser/validator complains about the ARTHEADER 
tag and is quiet if I change it to HEADER. However, the jade tool complains 
about the HEADER tag. What am I doing wrong?

Whew... I think I'm finally getting to the point where this is close to 
being presentable. Thanks to all of you for patience and help in tons of 
questions; I would not have come close to progressing this quickly without you.


-- 
Rodolfo J. Paiz
####@####.####

 :          1. Where I present something the user should type in, I
 : have used the COMPUTEROUTPUT tag to show the shell prompt so it's
 : not displayed in bold, and then the USERINPUT tag to show what
 : the user actually types.  However, it is then showing the output
 : on two separate lines; is there a way I can tell it not to do
 : this?

Try:

   <programlisting>
<prompt>[root@example]# </prompt><userinput>echo text</userinput>
<computeroutput>text</computeroutput>
   </programlisting>

This should give you the sort of spacing you desire.

[ I snipped questions 2 and 3.  I'll leave them for somebody else. ]

 :          4. If I try to create multiple HTML pages instead of
 : just one, the filenames are "t1.html" and "x76.html" which seems
 : very odd to me. Is there no way to suggest "howto-1.html" and
 : "howto-2.html" names? I remember the old sgml-tools used to name
 : them this way, and it seemed a much more intuitive method to me.

I, too, stumbled over this, and find that it's annoying and also
somewhat non-intuitive, however, the fix isn't too hard.

It's the famous "use-id-as-filename" flag, which is available with
different syntax in either a DSSSL or XSL processor.  Since you are
using Jade (correct?), you should add the following option to your
jade command:

  -V %use-id-as-filename%

http://docbook.sourceforge.net/release/dsssl/current/doc/html/use-id-as-filename.html


[ I snipped your last question, too. ]

Good luck!

-Martin

At 13:43 10/21/2003, David Lawyer wrote:
>On Mon, Oct 20, 2003 at 04:10:40PM -0600, Rodolfo J. Paiz wrote:
> > At 15:54 10/20/2003, David Lloyd wrote:
> > >What are you using the <BR> for? I didn't think that it existed in DocBook
> > >(or LinuxDoc for that matter).
>
>LinuxDoc uses <newline> for <BR>.  <newline> is so hard to type that I've
>made it into a macro so that I just type ;n to get it.  It's a nice
>substitute for <item> since you don't get any bullets, numbers, or
>indentation in the list and thus have more space for list content :-)

So, does such a thing exist in DocBook? (Yes, I'll go through the docs in a 
couple of hours to find out... but I might miss it, and someone else might 
have a 2-second answer.)


-- 
Rodolfo J. Paiz
####@####.####