NEWBIE: getting your document structure right.. :)

NEWBIE: getting your document structure right.. :)

[Dan Miner]

I've been playing with DocBook and reading what I can find for a couple of
days now.  I'm still coming up empty handed...

I'm making an electronic copy of an old book from the Commodore 64 days
written by Jim Butterfield.  I would really like to *capture* the structure
of the book and its content.  However, I've run into a couple of things I
can't quite identify approiate tags.

This book is about learning 650x machine language and the author uses
rather informal lists and examples.  I'm looking for something meaning this:

<Goals>
  <GoalDef>my goal</GoalDef>
  <GoalExplain>more details about why this goal is important, etc.</GoalExplain>
  <GoalDef>my goal 2</GoalDef>
  <GoalExplain>more text about why this goal is important, etc.</GoalExplain>
</Goals>

I understand display is somewhat a secondary concern but I'l hoping
for a display like:

	* my goal
	  more details about why this goal is important, etc.

	* my goal 2
	  more text about why this goal is important, etc.
	

Also, how can I express example information/code/command that is actually
part of the paragraph flow?

For example:

<para>Be sure to run <InlineExample role=eg>G C000</InlineExample> your newly
created program by using the monitor run or go command.</para>

Formatted as:
Be sure to run (e.g. G C000) your newly created program by using the
monitor run or go command.


Is there any hope for me?  :)


I'm using the docbook-tools (jade 1.2.1, 0.10, etc -- latest RPMs) and
the db2html for "display".

	Regards,
		Dan

-- 
 Dan Miner     dan@miner.org |   "That vulnerability is completely    | Doing
        Linux & UNIX         |      theoretical." -- Microsoft        | Linux
    Programmer/Consultant    | "What yonder light Windows 95 breaks?" | since
  http://www.dan.miner.org/  |    "Free software: The New Frontier"   | v0.12
------------------------------------------------------------------------------
       By filing this bug report, you have challenged the honor of my
       family.  PREPARE TO DIE!

Re: NEWBIE: getting your document structure right.. :)

[Jorge Godoy]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2013 bytes --]

On Tue, Feb 22, 2000 at 09:42:15PM -0700, Dan Miner wrote:
> 
> <Goals>
>   <GoalDef>my goal</GoalDef>
>   <GoalExplain>more details about why this goal is important, etc.</GoalExplain>
>   <GoalDef>my goal 2</GoalDef>
>   <GoalExplain>more text about why this goal is important, etc.</GoalExplain>
> </Goals>
> 
> I understand display is somewhat a secondary concern but I'l hoping
> for a display like:
> 
> 	* my goal
> 	  more details about why this goal is important, etc.
> 
> 	* my goal 2
> 	  more text about why this goal is important, etc.

It seems to me like a variablelist.

<propaganda>

I've started a HOWTO on DocBook (and I'm improving it for LDP's
2nd. version) and placed it in http://metalab.unc.edu/godoy - there's
a link to the Portuguese and English versions. There's explained how
to do this.

</propaganda>

<excuses>

English errors are being corrected, since the translator was not a
technical one. 

</excuses>

> Also, how can I express example information/code/command that is actually
> part of the paragraph flow?
> 
> For example:
> 
> <para>Be sure to run <InlineExample role=eg>G C000</InlineExample> your newly
> created program by using the monitor run or go command.</para>
> 
> Formatted as:
> Be sure to run (e.g. G C000) your newly created program by using the
> monitor run or go command.

You'll have to create this new element or modify some element's
appearance using a stylesheet. 


> Is there any hope for me?  :)

There's always hope. But it doesn't means that you'll do what you want
to :-))


Regards,
--
Godoy.	<godoy@conectiva.com.br>               GPG Fingerprint
                                         851B B620 626D 2AD0 E783
"Ser poeta não é minha ambição,          E932 1330 BE6D A4A3 0625 
 é minha maneira de estar sozinho"
              - Fernando Pessoa.       Publicações @ Conectiva S.A. 

Except where explicitly stated I speak on my own behalf.
Exceto onde explicitado as declarações aqui feitas são apenas minhas.

Re: NEWBIE: getting your document structure right.. :)

[Norman Walsh]

/ Jorge Godoy <godoy@conectiva.com.br> was heard to say:
| On Tue, Feb 22, 2000 at 09:42:15PM -0700, Dan Miner wrote:
| > 
| > <Goals>
| >   <GoalDef>my goal</GoalDef>
| >   <GoalExplain>more details about why this goal is important, etc.</GoalExplain>
| >   <GoalDef>my goal 2</GoalDef>
| >   <GoalExplain>more text about why this goal is important, etc.</GoalExplain>
| > </Goals>
| > 
| > I understand display is somewhat a secondary concern but I'l hoping
| > for a display like:
| > 
| > 	* my goal
| > 	  more details about why this goal is important, etc.
| > 
| > 	* my goal 2
| > 	  more text about why this goal is important, etc.
| 
| It seems to me like a variablelist.

I agree, with perhaps some stylesheet tweaks to get precisely that
formatting.

| > Also, how can I express example information/code/command that is actually
| > part of the paragraph flow?
| > 
| > For example:
| > 
| > <para>Be sure to run <InlineExample role=eg>G C000</InlineExample> your newly
| > created program by using the monitor run or go command.</para>
| > 
| > Formatted as:
| > Be sure to run (e.g. G C000) your newly created program by using the
| > monitor run or go command.
| 
| You'll have to create this new element or modify some element's
| appearance using a stylesheet. 

Oh, I really try to avoid that answer whenever possible because it makes
the documents much less portable. I'd be tempted myself to use
<literal>, <userinput>, or even <systemitem role="inlineexample">
before creating a new element.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | If you are hankering after
http://nwalsh.com/                 | certainty, you are better advised
                                   | to seek it in religion: the
                                   | stock-in-trade of science is not
                                   | certainty but doubt.--K.C. Cole

Re: NEWBIE: getting your document structure right.. :)

[Norman Walsh]

/ Dan Miner <dminer@edison.chisp.net> was heard to say:
| I've been playing with DocBook and reading what I can find for a couple of
| days now.  I'm still coming up empty handed...

You might want to join the DocBook list (docbook@lists.oasis-open.org).
That's an ideal place for general DocBook structure questions.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Every new beginning comes from
http://nwalsh.com/                 | some other beginning's end.