discuss: Thread: db2omf

Has anyone done any work on creating omf from our docbook sources?

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

Q:	How many lawyers does it take to change a light bulb?
A:	You won't find a lawyer who can change a light bulb.  Now, if
	you're looking for a lawyer to screw a light bulb...

Not yet, but I plan to. I've read the omf spec and it seems to me that I
should keep the omf in mind as I create the new DocBook template that I'm
going to be working on. So my plan is to analyze existing LDP DocBook files
to see what kinds of omf-type metadata they already have, and to find good
examples of each. I'll probably write some programs in Python to do that.
Then I'll take the best examples I can find, plus the omf recommendations,
to create a new template. Then I could write another Python program to
compare existing files against the template to see what pieces are missing
from existing docs that could be added by their authors. Then I could also
create a program to extract the omf pieces from existing docs in a form that
could be submitted to the omf repository. How does that sound?

---
Patrick K. O'Brien
Orbtech (http://www.orbtech.com)
"I am, therefore I think."

-----Original Message-----
From: David Merrill ####@####.####
Sent: Thursday, March 08, 2001 10:58 AM
To: ldp-discuss
Subject: db2omf

Has anyone done any work on creating omf from our docbook sources?

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

Q:      How many lawyers does it take to change a light bulb?
A:      You won't find a lawyer who can change a light bulb.  Now, if
        you're looking for a lawyer to screw a light bulb...

_________________________
http://list.linuxdoc.org/

I'm adding some detail to the "Encoding Indexes" section of the LDP Author
Guide.  Greg Ferguson suggested that it might be a good idea to include
information about creating OMF entries in this section.  I'd be happy to
document this process and put it in the Guide, if someone would give me a
brief explanation.

Thanks,
Kristin

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Kristin Thomas
Linux Information Development
Linux Technology Center
Ph. (512) 838-4546
T/L 678-4546
Bldg. 908 1D002

On Thu, Mar 08, 2001 at 12:20:05PM -0600, Patrick K. O'Brien wrote:
> Not yet, but I plan to. I've read the omf spec and it seems to me that I
> should keep the omf in mind as I create the new DocBook template that I'm
> going to be working on. So my plan is to analyze existing LDP DocBook files
> to see what kinds of omf-type metadata they already have, and to find good
> examples of each. I'll probably write some programs in Python to do that.
> Then I'll take the best examples I can find, plus the omf recommendations,
> to create a new template. Then I could write another Python program to
> compare existing files against the template to see what pieces are missing
> from existing docs that could be added by their authors. Then I could also
> create a program to extract the omf pieces from existing docs in a form that
> could be submitted to the omf repository. How does that sound?

Sounds good. I do have a couple of comments and suggestions.

We already have (I think) two templates, one for large docs and one
for regular docs, i.e., an <article> and a <book>. Look at them
(you'll find them in the LAG) and use them as you can. There is much
there that is already good; what they lack is the task I asked you to
do, which is a "recommended" "standard" outline. They already have
pretty good examples of tag usage and some comments that are helpful.

If I'm wrong about having <article> and <book> then at least we
*should* have <article> (i.e., HOWTO) and <book> (i.e., Guide)
templates. Their needs are sufficiently different.

Make your template using the latest version of DocBook, and preferably
in both SGML and XML. They're very close, so it won't take much to do
it.

The omf we need to generate should be compatible with scrollkeeper
because I believe scrollkeeper will be the way we access our
documentation a year from now. Download and install sk from
sourceforge (scrollkeeper.sourceforge.net) and look at the sample omf
in /usr/share/omf.

All else being equal, perl has the advantage of more available
programmers. I'm not the language police, though, so use what you
like.

License under GPL, and I will want to donate the scripts to
scrollkeeper because they will need this functionality also.

That's all I can think of atm. Good luck, and thanks.

> -----Original Message-----
> From: David Merrill ####@####.####
> Sent: Thursday, March 08, 2001 10:58 AM
> To: ldp-discuss
> Subject: db2omf
> 
> Has anyone done any work on creating omf from our docbook sources?
> 
> --
> Dr. David C. Merrill                     http://www.lupercalia.net
> Linux Documentation Project                   ####@####.####
> Collection Editor & Coordinator            http://www.linuxdoc.org
>                                        Finger me for my public key
> 
> Q:      How many lawyers does it take to change a light bulb?
> A:      You won't find a lawyer who can change a light bulb.  Now, if
>         you're looking for a lawyer to screw a light bulb...
> 
> _________________________
> http://list.linuxdoc.org/
> 
> 
> _________________________
> http://list.linuxdoc.org/

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

Disraeli was pretty close: actually, there are Lies, Damn lies, Statistics,
Benchmarks, and Delivery dates.

On Thu, Mar 08, 2001 at 12:24:58PM -0600, Kristin E Thomas wrote:
> I'm adding some detail to the "Encoding Indexes" section of the LDP Author
> Guide.  Greg Ferguson suggested that it might be a good idea to include
> information about creating OMF entries in this section.  I'd be happy to
> document this process and put it in the Guide, if someone would give me a
> brief explanation.

afaik, there is no reason anyone should have to manually write omf
files. All the necessary metadata is already in docbook, if it has
been used. You might want to wait a week or two do write that section,
because it looks like we will have a script to do it that soon. It
isn't *that* big of a job for a good programmer. If I knew perl I
would have done it myself by now.

As usual, in my copious free time. :-)

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

People that can't find something to live for always seem to find something to
die for.  The problem is, they usually want the rest of us to die for it too.

On Mar 8, 12:25pm, Kristin E Thomas wrote:
> Subject: Re: db2omf
> I'm adding some detail to the "Encoding Indexes" section of the LDP
> Author Guide.  Greg Ferguson suggested that it might be a good idea
> to include information about creating OMF entries in this section.
> I'd be happy to document this process and put it in the Guide, if
> someone would give me a brief explanation.

Here's some good content on the hows/whys of the OMF engine:

   http://www.ibiblio.org/osrt/omf/faq.html

I think it's important for an author to understand how to
include proper metadata in *their* DocBook documents so that
it can be parsed and *feed* the OMF engine easily. This gives
the author an idea on how this data can be effectively used and
why we "require" (strongly advocate?) it.

r,
Ferg

On Thu, Mar 08, 2001 at 01:25:35PM -0500, Greg Ferguson wrote:
> On Mar 8, 12:25pm, Kristin E Thomas wrote:
> > Subject: Re: db2omf
> > I'm adding some detail to the "Encoding Indexes" section of the LDP
> > Author Guide.  Greg Ferguson suggested that it might be a good idea
> > to include information about creating OMF entries in this section.
> > I'd be happy to document this process and put it in the Guide, if
> > someone would give me a brief explanation.
> 
> Here's some good content on the hows/whys of the OMF engine:
> 
>    http://www.ibiblio.org/osrt/omf/faq.html
> 
> I think it's important for an author to understand how to
> include proper metadata in *their* DocBook documents so that
> it can be parsed and *feed* the OMF engine easily. This gives
> the author an idea on how this data can be effectively used and
> why we "require" (strongly advocate?) it.

Abso-fsck-ing-lutely.

Patrick and Karen, maybe you two can work together on this. On further
thought, Karen, it would be great to have the LAG detail exactly what
db tags result in what omf fields. You could document that. It won't
change regardless of the way the script changes the omf creation
process. Patrick can write the script that does the transfer, and
you can work together to create a template that works with the script
and generates sample omf.

Patrick, if you pull from anonymous cvs you will find the db howtos in
a separate directory, so you can easily test your script on lots of
docs. Just a thought.

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

If the government doesn't trust the people, why doesn't it dissolve them
and elect a new people?

Greg Ferguson wrote:
> Here's some good content on the hows/whys of the OMF engine:
> 
>    http://www.ibiblio.org/osrt/omf/faq.html
> 
> I think it's important for an author to understand how to
> include proper metadata in *their* DocBook documents so that
> it can be parsed and *feed* the OMF engine easily. This gives
> the author an idea on how this data can be effectively used and
> why we "require" (strongly advocate?) it.

Sorry, this doesn't explain much to me.  If DB tags can be converted
to OMF data, then why bother documenting it?  If DB already includes
indexing, why use OMF?  Is OMF supposed to be a meta-search engine?  What
makes it different from google, aside from the fact that google indexes
everything, not just open source documentation?

If this is just a matter of "make sure these tags are filled out", let
me know what the tags in question are, and I'll put it in the style
section.

-Mark

-- 
Mark Komarinski - Senior Systems Engineer - VA Linux Systems
(cell)  978-697-2228
(email) ####@####.####
"Have one day pleasant" - Babelfish

Sounds reasonable to me. But is it Karen or Kristin who is working on the
LAG?

---
Patrick K. O'Brien
Orbtech (http://www.orbtech.com)
"I am, therefore I think."

-----Original Message-----
From: David Merrill ####@####.####
Sent: Thursday, March 08, 2001 12:35 PM
To: ####@####.####
Subject: Re: db2omf
Abso-fsck-ing-lutely.

Patrick and Karen, maybe you two can work together on this. On further
thought, Karen, it would be great to have the LAG detail exactly what
db tags result in what omf fields. You could document that. It won't
change regardless of the way the script changes the omf creation
process. Patrick can write the script that does the transfer, and
you can work together to create a template that works with the script
and generates sample omf.

Patrick, if you pull from anonymous cvs you will find the db howtos in
a separate directory, so you can easily test your script on lots of
docs. Just a thought.

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

If the government doesn't trust the people, why doesn't it dissolve them
and elect a new people?

_________________________
http://list.linuxdoc.org/

I'll handle it, once we figure out what has to be done.  I'm not sure
this is something that should be in the using DocBook section, probably
better suited to the style guide.

-Mark

"Patrick K. O'Brien" wrote:
> 
> Sounds reasonable to me. But is it Karen or Kristin who is working on the
> LAG?
> 
> ---
> Patrick K. O'Brien
> Orbtech (http://www.orbtech.com)
> "I am, therefore I think."
> 
> -----Original Message-----
> From: David Merrill ####@####.####
> Sent: Thursday, March 08, 2001 12:35 PM
> To: ####@####.####
> Subject: Re: db2omf
> Abso-fsck-ing-lutely.
> 
> Patrick and Karen, maybe you two can work together on this. On further
> thought, Karen, it would be great to have the LAG detail exactly what
> db tags result in what omf fields. You could document that. It won't
> change regardless of the way the script changes the omf creation
> process. Patrick can write the script that does the transfer, and
> you can work together to create a template that works with the script
> and generates sample omf.
> 
> Patrick, if you pull from anonymous cvs you will find the db howtos in
> a separate directory, so you can easily test your script on lots of
> docs. Just a thought.
> 
> --
> Dr. David C. Merrill                     http://www.lupercalia.net
> Linux Documentation Project                   ####@####.####
> Collection Editor & Coordinator            http://www.linuxdoc.org
>                                        Finger me for my public key
> 
> If the government doesn't trust the people, why doesn't it dissolve them
> and elect a new people?
> 
> _________________________
> http://list.linuxdoc.org/
> 
> _________________________
> http://list.linuxdoc.org/

-- 
Mark Komarinski - Senior Systems Engineer - VA Linux Systems
(cell)  978-697-2228
(email) ####@####.####
"Have one day pleasant" - Babelfish