Re: if SGML is so great...

[pac1@tiac.net]

>   pac1 wrote:

>
> > I'm thinking of parameters which have a set of specific
> > values with different
> > meanings or set of ranges of values with different meanings.
> >
> > Does Doc-Book have the tags to identify this kind of information?

>
> Gregory Leblanc wrote:

> Of course!  :-)  Take a look at the tags for <variablelist> and related
> tags.  Here's something kinda similar taken from the source of the GNOME
> Calculator doc that I'm working on.  I've modified it so that it's more
> applicable as a template.  Keep in mind that it looks like krap in email,
> but is quite readable in some editor that does syntax hightlighing.
>
>    <variablelist>
>     <varlistentry>
>      <term>PARAMETER</term>
>      <listitem>
>       <para>
>        DESCRIPTION OF PARAMETER
>        <example>
>         <title>PARAMETER</title>
>         <para>EXAMPLE OF HOW TO USE PARAMETER</para>
>        </example>
>       </para>
>      </listitem>
>     </varlistentry>
>
>
>    <variablelist>
>     <varlistentry>
>      <term>PARAMETER</term>
>      <listitem>
>       <para>
>        DESCRIPTION OF PARAMETER
>        <example>
>         <title>PARAMETER</title>
>         <para>EXAMPLE OF HOW TO USE PARAMETER</para>
>        </example>
>       </para>
>      </listitem>
>     </varlistentry>
>
> Hmm, not sure about how to put in "possible value of parameter" if you're
> trying to make a complete list of all of the possibilities.  You might use
> another <variablelist> inside of it.  If you need more clarification let me
> know.
>         Greg

Perhaps I should explain what I'd like to be able to do..

I'd like to be able to take sets of documentation and extract the following
kinds of information under program control:

o  A list of commands with frequently used options explained
o  A list of commands with frequently used combinations of options and
explanations of the purpose of the combinations
o  A list of definitions of terms used in explaining a command
o  A list of "frequently used options and option values"
o  A full list of options and parameters with explanations and examples


In short, to be able to produce different views of the documentation not just
in different formats, but with different levels of detail and differing focus
in the content view.

I'm thinking about these kind of questions:

"How do I use X to do Y?"
"What do I use to do Y?"
"What can I use X for?"
"What do most people use X for most of the time?  Give examples of just that."

"What have I done with X?"
"I know I've done Y but I can't remember exactly how.  What did I do to do Y?"

"What have I done?  Why did I do that?..."


Here's an idea for an application I've never seen anywhere:

Basic idea:  Keep a record of personal command, option and parameter usage
                    Combine personal command usage data with documentation for
searching purposes.
                     Combine the personal command usage data of others with
your own personal command
                     usage data and with documentation
                     Use the web, Luke!


"What commands, options and parameters have I personally used to do my work in
the past 3 months?  What matches on the way I've used them can be found  in
the documentation.  Present a searchable combined view of every command
combination I've used without getting an error message in the last n days and
the documentation for those commands and option combinations.  Let me search
the combined view.  Present the results in a nice table.  If I don't find what
I'm looking for,  expand the search to all the "popular" combinations in
examples from the documentation.  If that doesn't do it expand the search to
less frequently used combinations of options.

Want to make it even more fun?  start trading command usage records via tcp-ip
with others with similar interests.  Combine that information and use that as
the basis of a search.  Combine the documentation and the usage data with
other information gleaned from mailing lists.    If you're stuck on a
particular point, find others similarly stuck in the last n hours who are now
un-stuck see what they did.


Anyway, with an appropriate Data type definition, you could use documentation
written to the DTD to extract and combine the information in the documentation
with other information.  I don't know if Doc-Book is the "right" dtd for this
or not.  I'm learning it now.












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