Re: [Scrollkeeper-devel] ScrollKeeper-0.1 Proposal #3

[Nik C. <ni...@fr...>]

On Sun, Nov 12, 2000 at 10:22:33PM -0600, Dan Mueth wrote:
> Hi everybody,

Ditto.  A brief intro -- I'm the FreeBSD Documentation Project cat herder.
I was at the O'Reilly conference earlier this year, and I subscribed to this
list a few days ago.  I've been working my way through the archives :-)

> Feedback is welcome :)

OK :-)

>                 --------------------------------------
>                 |   ScrollKeeper 0.1 - Proposal #3   |
>                 --------------------------------------
>
> II. Building, Installing, and Uninstalling
> 
> i. Building
> 
> The OMF documents are manipulated during the application
> build process, generally as part of 'make all'.  The purpose of this
> is to (1) substitute the correct URL of the document where it will
> actually be installed, which is not generally known until build time,
> and to (2) extract the OMF from DocBook documents into a seperate file.
> (NOTE: #2 may not be supported in ScrollKeeper 0.1)

You probably don't know where the application is going to be installed until
install time, not build time.  Using the FreeBSD ports tree, it's trivial
to do

    cd /usr/ports/foo/bar
    make
    make PREFIX=/somewhere/else install

Similarly, if you're building packages on BSD (or RPMs, or whatever) the
end user can change the install path after the package has been built, but
before it has been installed.

I know that FreeBSD packages and RPMs both support running commands after
the install -- I assume the .deb format does as well. 

> Note that the OMF file is named <application>-<document_title>-<locale>.omf.
> This is important to avoid collisions between OMF files when they are
> installed. 

Your examples don't use a sufficiently long <locale>.  For example, the user
might install docs in Chinese, using both EUC and Big 5 encoding.  For that,
you really need to be able to specify zh_CN.EUC and zh_TW.Big5.

Note that trying to rely on just zh_CN or zh_TW isn't sufficient for other
languages, like Japanese, where the various encodings hang off a ja_JP
prefix.

> Installation is done by first copying the document and OMF file into
> place and then having ScrollKeeper update its database by calling 
> 'scrollkeeper-update'.

Seems reasonable.

> install:
> 	install foo-manual.sgml $(DOCDIR)
> 	install omf-install/foo-manual-fr.omf $(OMFDIR)
> 	scrollkeeper-update -p $(SCROLLKEEPER_DB_DIR)

An option to specify exactly where you installed the documentation is
probably a good idea, so that scrollkeeper-update doesn't have to rescan
a (potentially) huge directory tree of documentation.

> -- For use by help browsers --
> scrollkeeper-get-contents-list <language>:
>   1) Returns the path:
>         ${pkglocalstatedir}/<language>/scrollkeeper-contents-list.xml

Should a lot of this stuff be implemented only as separate programs?  What
about a scrollkeeper library that applications can link with that provides
functions that return this information from a config file somewhere.  Having
to run several applications every time someone starts their help browser may
not be very efficient.

> scrollkeeper-contents-list.xml:
> 	This is a simple XML file which reveals what the Contents List
> 	looks like and where the OMF files and doc are at. This is used
> 	by the help browser to display the Contents List.
> 	[We will need to write up a simple DTD.]
> 
>    <sect>
>      <title>Applications</title>
>      <sect>
>        <title>Games</title>
>        <doc docid="000050">
>          <doctitle>FreeCell</doctitle>
>          <docomf>/usr/local/games/freecell/freecell-omf.xml</docomf>
>          <docsource>/usr/local/games/freecell/freecell.sgml</docsource>
>          <docformat>SGML</docformat>
>        </doc>
>      </sect>
>    </sect>

<snip>

> scrollkeeper-extended-contents-list.xml:
> 	Similar to scrollkeeper-contents-list.xml, except has TOC info in
> 	it too.  This is used by the help browser to display the
> 	"extended Contents List".

What's the rationale for keeping these separate?  Any program iterating
over their contents should know whether it needs the extended information or
not, and ignore it, or process it, as necessary.

The choice of element or attribute in your sample is inconsistent.  Either
something like

   ...
   <doc id="00050" omf="..." source="..." format="sgml">
     <title>Freecell</title>
   </doc>

or

   <doc>
     <docid>00050</docid>
     <title>...</title>
     ...
   </doc>

might be better.  When I first started writing DTDs, I was advised on 
several mailing lists that if you expect to show content to the end user
(such as the title) then make it an element.  Anything that is designed to
help the application (such as the format, or the source) is an attribute.

Of course, there's a case for saying that "Well, the application will be
able to show the user an icon for the source format, or the path to the
underlying document" so it's not a cut and dried decision.  It's probably
best to consider what the default view would be.

N
-- 
Internet connection, $19.95 a month.  Computer, $799.95.  Modem, $149.95.
Telephone line, $24.95 a month.  Software, free.  USENET transmission,
hundreds if not thousands of dollars.  Thinking before posting, priceless.
Somethings in life you can't buy.  For everything else, there's MasterCard.
  -- Graham Reed, in the Scary Devil Monastery