DOCBOOK-APPS: Re: DOCBOOK: Announce: Website 2.0a1 (ALPHA) released

[Norman Walsh <ndw@nwalsh.com>]

/ Dave Pawson <daveP@dpawson.freeserve.co.uk> was heard to say:
[...]
| Can I specify
| 
| <tocentry page="doc1.xml" dir="subdir1/subdir2"
|               filename="index.html">
|  to request the output file be put two dirs deep?

Yes.

| Will
|    <tocentry page="directory1/doc1.xml" dir="subdir"
|               filename="index.html">
| pull doc1.xml from directory1, if I ever get round to sorting
| out all the xml files :-)

Yes.

| "<para>By default, directories are inherited (hence
| <filename>page2.html</filename> and <filename>page3.html</filename>
| will appear in the <filename>subdir</filename> directory)</para>"
| 
| What does this mean please Norm? Specifically, the 'directories 
| are inherited'? 

The directory for a tocentry comes from the <tocentry> tag or the
closest enclosing <tocentry> (or <toc>) that has a directory specified.

If you say:

    <tocentry page="doc1.xml" dir="subdir"
              filename="index.html">
      <tocentry page="doc1.1.xml" filename="page2.html"/>
      <tocentry page="doc1.2.xml" filename="page3.html"/>

The result will be:

  doc1.xml -> subdir/index.html
  doc1.1.xml -> subdir/page2.html
  doc1.2.xml -> subdir/page3.html

The "subdir" was "inherited".

| 4. Typo? wslayout.xml
| <programlisting>
|   + index.html
|     + subdir/index.html
|       + subdir/page2.html
|       + subdir/page2.html
|     + page2.html
| </programlisting>

Yes. Typo.

| Does this exemplify last point in 3, directory inheritance?
|   E.g. I don't need to specify that the second html file in subdir
|   needs to be put in subdir? E.g.
|
| <layout>
|   <toc page="website.xml" filename="index.html">
|     <tocentry page="doc1.xml" dir="subdir"
|               filename="index.html">
|       <tocentry page="doc1.1.xml" filename="page2.html"/>
|       <tocentry page="doc1.2.xml" filename="page3.html"/>
|     </tocentry>
|     <tocentry page="doc2.xml" filename="page2.html"/>
|   </toc>
| </layout>
| 
| Implies that pages 2 and 3, being children of tocentry with subdir 2,
| are both 'in' subdir2? Just to confirm I think!

Uh-huh.

| 5. 'If a directory is not specified, the files will appear in the currently
| inherited directory (or in the root, if no directory is specified anywhere
| in the <sgmltag>tocentry</sgmltag> ancestry).'
| 
| Definition of 'root' please? Is this root of the file system, or 
| root relative to the build point, the root relative to the first 
| xml file processed... or something else?

Mumble. That depends a little bit. Each website must occupy a single
directory tree. If you don't specify a directory, the file will go
in the logical root of that tree.

This is probably going to be the directory you ran the build command in,
but you can change that with the output-root parameter.

| 6. <notoc> ..... I guess these must be explicitly linked to then?
|   As per the 'about' example?

Yes.

| 7. The example discussed, doesn't actually have an 'index.html'
|   derived from website.xml

Uhm.

| 8. There is no example usage of tocskip.

Sure there is. Click on the 'Building' link in the TOC and you'll be
taken to the 'Using Make' subpage.

| 9. Relative references.
|    I've lost track of your directory layout Norm, in chunk-website you
|     have ../../xsl/html/chunker.xsl
| 
|     are you expecting the following layout?
|      docbook
|      website
|          xsl
| 
|    if not, what does the default expect please?

Oh, barf. I want a @%@%!!$# entity resolver.

  docbook/xsl/...           normal stylesheets
  docbook/website/xsl/...   website stylesheets

But you can hack the relative references if necessary.

| 10. Last error, was the xbel bookmarks, called up from autolayout.xml.

Oh, yeah, I need to check that stuff. Thanks.

| 1. The link to the text only version, txtindex.html, is invalid,
|    is that a build option?

You have to build the text-only version separately. Sigh.

  make TEXTONLY=1

I think.

| Biggest change will be directory layout.
| I copied yours once, though the XSL additions I guess I made
| a  bad guess at where you were going to put them!
|    Given
|     nw
|       docbook
|         etc - std docbook 412 dtd
|     where would you expect to see the XSL please? Inside docbook?
|     and where does the website sit relative to this?
|     Are you happy that the two dtd's stay in the website area?
|     Again I suppose its a catalog thing?

The whole layout is more-or-less a catalog thing. If you copy the
SourceForge layout, it'll work "out of the box". But I may change
the relative references to point to the web, too.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Curiosity will conquer fear even
http://www.oasis-open.org/docbook/ | more than bravery will.--James
Chair, DocBook Technical Committee | Stephens