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

Re: Requiring use of DocBook; LinuxDoc




Ok, let's remove those unlikely to be useful in an HOWTO para ...

>>>>> "G" == Gary Preckshot <garrell@inreach.com> writes:

    G> ELEMENT Para = (( #PCDATA | Abbrev |

    G> Acronym | Emphasis | ULink | Application | ClassName | Command
    G> | ComputerOutput | Email | EnVar | ErrorCode | ErrorName |
    G> Filename | Function | GUIButton | GUIIcon | GUILabel | GUIMenu
    G> | GUIMenuItem | GUISubmenu | Hardware | InterfaceDefinition |
    G> KeyCap | KeyCode | KeySym | Literal | Constant | MenuChoice |
    G> MouseButton | MsgText | Option | Parameter | Prompt |
    G> ReturnValue | StructField | StructName | Symbol | Token | Type
    G> | UserInput | VarName | Subscript | Superscript |
    G> InlineMediaObject | ItemizedList | OrderedList | SimpleList |
    G> VariableList | Caution | Important | Note | Tip | Warning |
    G> LiteralLayout | ProgramListing | Screen | ScreenShot |
    G> MediaObject | Table)+)

Which one do you not understand?

Does LinuxDoc distinguish computer output from screenshots and program
listings?  Does it distinguish between a keycap, a key code and the
key symbol?  How do you specify a GUI Icon in LinuxDoc.

That last one is most illustrative: I am finding I can write far more
clearly and succinctly in DocBook when I know I can trust the
typographic conventions to be consistent across _all_ DocBook
documents. For example, in docbook I could write

    Click on <GUIICON>Printer</GUIICON> then select
    <GUIMENUITEM>lp2</GUIMENUITEM>

whereas in LinuxDoc/ASCII I would need to resolve this semantically
with extra language

Click on the Printer Icon on your desktop, then 
select the lp2 option from the menu.

The first version is 6 characters _less_ typing, and it is
considerably less characters for the reader to scan.  Considering I am
not afraid of Emacs, the first version is actually only 49 keystrokes
(using tagname completion) vs 85 keystrokes for the ASCII version.
That gives me lots of spare keystrokes to first scan the list of
allowable tags to find the one most appropriate to my meaning.

-- 
Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723
TCI - Business Innovations through Open Source : http://www.teledyn.com
Love Linux?  We need authors/reviewers - http://www.teledyn.com/authors



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