docbook-apps

  • 1.  Getting a mapping between id's and output files

    Posted 11-15-2022 23:49
    Hi all

    I have a desktop app and I have written documentation for this app in
    DocBook. I am producing webhelp and posting these html pages online. From
    within my application I would like to be able to open pages from the online
    webhelp in a local browser. All of this works nicely so far.

    The problem is knowing which page to open for a given topic. To solve this
    problem I would like to produce a file that contains the mappings between
    all of the id attributes that are declared in my document and the name of
    the chunked html output file that contains the id. Ideally the mapping
    would be to the chunk plus anchor if the element containing the id is not
    the outermost section, chapter, appendix, etc of the chunk. Then from
    within my app I can look up the mapping for a given id, and request the
    browser to open the desired page.

    I expect that this is something that can be done using xslt technology, but
    I do not know where to begin. I am at the skill level where I have made a
    few small customizations in a project that used xslt, but I don't really
    know how to go about opening a file and writing output, where to find the
    id value, where to find the chunk name, etc. In other words a beginner
    looking at the start of a steep learning curve.

    Can someone point me in the right direction for this task? I notice that
    the javahelp output creates a mapping file that is almost right, except
    that it does not use the chunk names derived from the filename=""?> processing instructions, which I am using in order to get
    links that don't shift around as I add chapters and sections. Is the
    javahelp tool a good starting point or would it be better to start from
    scratch? Is there a book that you would recommend that is good to learn
    from?

    Thanks,

    Tom



  • 2.  Re: [docbook-apps] Getting a mapping between id's and output files

    Posted 11-16-2022 01:42
    Hi Tom,

    You can generate something like what you need already using the olink
    mechanism.  If you set the stylesheet parameter 'collect.xref.targets'
    to a value of 'yes', then when you process your document for HTML output
    you will also generate a target.db file that is used in olinking
    (there's a parameter to rename that file).  It is an XML file that
    contains all potential cross reference targets for that document.  In
    that file, the
    elements hold the info for the hierarchical
    elements, and <obj> elements contain the info for the nonhierarchical
    elements (tables, figures, etc.).  For each, its targetptr attribute
    contains the element's id, and its href attribute contains the link to
    that element in your output.

    Your app could open that file, or you could further process it with a
    simple stylesheet to refine it.

    Check out this chapter in my book on olinking:

    http://www.sagehill.net/docbookxsl/Olinking.html

    Bob

    On 11/15/2022 3:49 PM, Tom Moore wrote:
    > Hi all
    >
    > I have a desktop app and I have written documentation for this app in
    > DocBook.  I am producing webhelp and posting these html pages online. 
    > From within my application I would like to be able to open pages from
    > the online webhelp in a local browser.  All of this works nicely so far.
    >
    > The problem is knowing which page to open for a given topic.  To solve
    > this problem I would like to produce a file that contains the mappings
    > between all of the id attributes that are declared in my document and
    > the name of the chunked html output file that contains the id. 
    > Ideally the mapping would be to the chunk plus anchor if the element
    > containing the id is not the outermost section, chapter, appendix, etc
    > of the chunk.  Then from within my app I can look up the mapping for a
    > given id, and request the browser to open the desired page.
    >
    > I expect that this is something that can be done using xslt
    > technology, but I do not know where to begin.  I am at the skill level
    > where I have made a few small customizations in a project that used
    > xslt, but I don't really know how to go about opening a file and
    > writing output, where to find the id value, where to find the chunk
    > name, etc.   In other words a beginner looking at the start of a steep
    > learning curve.
    >
    > Can someone point me in the right direction for this task? I notice
    > that the javahelp output creates a mapping file that is almost right,
    > except that it does not use the chunk names derived from the > filename=""?> processing instructions, which I am using in order to
    > get links that don't shift around as I add chapters and sections.  Is
    > the javahelp tool a good starting point or would it be better to start
    > from scratch?  Is there a book that you would recommend that is good
    > to learn from?
    >
    > Thanks,
    >
    > Tom


  • 3.  Re: [docbook-apps] Getting a mapping between id's and output files

    Posted 11-16-2022 20:52
    Well that is just brilliant and solves my problem 100%. The target.db file
    contains the information I need in an easily parsable format. Thank you
    very much for this advice.

    Cheers,

    Tom
    P.S. I just ordered a copy of your book.

    On Tue, Nov 15, 2022 at 8:47 PM Bob Stayton <bobs@sagehill.net> wrote:

    > Hi Tom,
    >
    > You can generate something like what you need already using the olink
    > mechanism. If you set the stylesheet parameter 'collect.xref.targets' to a
    > value of 'yes', then when you process your document for HTML output you
    > will also generate a target.db file that is used in olinking (there's a
    > parameter to rename that file). It is an XML file that contains all
    > potential cross reference targets for that document. In that file, the
    >
    elements hold the info for the hierarchical elements, and <obj>
    > elements contain the info for the nonhierarchical elements (tables,
    > figures, etc.). For each, its targetptr attribute contains the element's
    > id, and its href attribute contains the link to that element in your output.
    >
    > Your app could open that file, or you could further process it with a
    > simple stylesheet to refine it.
    >
    > Check out this chapter in my book on olinking:
    >
    > http://www.sagehill.net/docbookxsl/Olinking.html
    >
    > Bob
    > On 11/15/2022 3:49 PM, Tom Moore wrote:
    >
    > Hi all
    >
    > I have a desktop app and I have written documentation for this app in
    > DocBook. I am producing webhelp and posting these html pages online. From
    > within my application I would like to be able to open pages from the online
    > webhelp in a local browser. All of this works nicely so far.
    >
    > The problem is knowing which page to open for a given topic. To solve
    > this problem I would like to produce a file that contains the mappings
    > between all of the id attributes that are declared in my document and the
    > name of the chunked html output file that contains the id. Ideally the
    > mapping would be to the chunk plus anchor if the element containing the id
    > is not the outermost section, chapter, appendix, etc of the chunk. Then
    > from within my app I can look up the mapping for a given id, and request
    > the browser to open the desired page.
    >
    > I expect that this is something that can be done using xslt technology,
    > but I do not know where to begin. I am at the skill level where I have
    > made a few small customizations in a project that used xslt, but I don't
    > really know how to go about opening a file and writing output, where to
    > find the id value, where to find the chunk name, etc. In other words a
    > beginner looking at the start of a steep learning curve.
    >
    > Can someone point me in the right direction for this task? I notice that
    > the javahelp output creates a mapping file that is almost right, except
    > that it does not use the chunk names derived from the > filename=""?> processing instructions, which I am using in order to get
    > links that don't shift around as I add chapters and sections. Is the
    > javahelp tool a good starting point or would it be better to start from
    > scratch? Is there a book that you would recommend that is good to learn
    > from?
    >
    > Thanks,
    >
    > Tom
    >
    >