docbook-apps

  • 1.  Bibliographic styling

    Posted 05-23-2020 00:24
    I’m thinking of taking on the task of creating a docbook customization, similar to the iso690 customization, to process bibliographic information in the Chicago Manual of Style format.

    Before I dive in head first, I thought I’d check with the group to see if anyone has already done that.

    Also, I have an additional question that might more appropriately belong in the docbook list, but I’ll give it a shot:

    To streamline the markup of inline references to bibliographic entries, I wonder whether it would stretch the standard too far to interpret a linkend in a citetitle as pointing to a bibliographic reference and process it as though it were a biblioref immediately following the citetitle. So, for example,

    <citetitlef pubwork=“book” linkend=“ref.stayton2007”>DocBook XSL: The Complete Guide</citetitle>

    would be interpreted as equivalent to <citetitle pubwork=“book”>DocBook XSL: The Complete Guide</citetitle><biblioref linkend=“ref.stayton2007”/>

    Since the ultimate result is a link (the only difference is that the link text would be an inline tag, e.g., [Stayton 2007], rather than the title text), I don’t think it’s too far out there.

    But, to take it a step further, how about interpreting <citetitle pubwork=“book” linkend=“ref.stayton2007”/>
    the same way, but pulling the title from the referenced biblioentry/bibliomixed element when the citetitle element is empty.

    Any thoughts?

    Best regards,
    Dick Hamilton
    -------
    XML Press
    XML for Technical Communicators
    http://xmlpress.net
    hamilton@xmlpress.net






  • 2.  Re: [docbook-apps] Bibliographic styling

    Posted 05-23-2020 11:43
    Richard Hamilton <hamilton@xmlpress.net> writes:
    > I’m thinking of taking on the task of creating a docbook
    > customization, similar to the iso690 customization, to process
    > bibliographic information in the Chicago Manual of Style format.
    >
    > Before I dive in head first, I thought I’d check with the group to see
    > if anyone has already done that.

    I wonder if it would be possible to describe the format in some
    declarative way and either derive the stylesheet from that or interpret
    it?

    I looked briefly at doing that with BibTeX once, but that seemed a
    little too challenging for the amount of free time that I have (which is
    generally measured in negative numbers).

    > To streamline the markup of inline references to bibliographic
    > entries, I wonder whether it would stretch the standard too far to
    > interpret a linkend in a citetitle as pointing to a bibliographic
    > reference and process it as though it were a biblioref immediately
    > following the citetitle. So, for example,
    >
    > <citetitlef pubwork=“book” linkend=“ref.stayton2007”>DocBook XSL: The Complete Guide</citetitle>
    >
    > would be interpreted as equivalent to <citetitle
    > pubwork=“book”>DocBook XSL: The Complete Guide</citetitle><biblioref
    > linkend=“ref.stayton2007”/>

    That doesn’t seem unreasonable to me. What I tend to do myself, however,
    is just the following:

    <biblioref linkend="ref.stayton2007"/>

    Which I then render inline as the title from the bibliography entry with
    whatever styling seems appropriate. Saves me from having to type the
    titles each time.

    > But, to take it a step further, how about interpreting <citetitle
    > pubwork=“book” linkend=“ref.stayton2007”/> the same way, but pulling
    > the title from the referenced biblioentry/bibliomixed element when the
    > citetitle element is empty.
    >
    > Any thoughts?

    That’s what biblioref is for? :-)

    Be seeing you,
    norm

    --
    Norman Tovey-Walsh <ndw@nwalsh.com>
    https://nwalsh.com/

    > Next to knowing when to seize an opportunity, the most important thing
    > in life is to know when to forego an advantage.--Benjamin Disraeli



  • 3.  Re: [docbook-apps] Bibliographic styling

    Posted 05-23-2020 12:44
    Richard,

    Would it be possible to step back a level and work on it in combination
    with CSL? https://citationstyles.org/ That way, it would not just be
    limited to CMOS. (Although having CMOS would be a major bonus for me.)
    The Github repo for the CSL styles are
    https://github.com/citation-style-language/styles
    There are a few on that list I would find extremely helpful.

    Peter

    On Sat, 23 May 2020 at 12:43, Norman Tovey-Walsh <ndw@nwalsh.com> wrote:

    > Richard Hamilton <hamilton@xmlpress.net> writes:
    > > I’m thinking of taking on the task of creating a docbook
    > > customization, similar to the iso690 customization, to process
    > > bibliographic information in the Chicago Manual of Style format.
    > >
    > > Before I dive in head first, I thought I’d check with the group to see
    > > if anyone has already done that.
    >
    > I wonder if it would be possible to describe the format in some
    > declarative way and either derive the stylesheet from that or interpret
    > it?
    >
    > I looked briefly at doing that with BibTeX once, but that seemed a
    > little too challenging for the amount of free time that I have (which is
    > generally measured in negative numbers).
    >
    > > To streamline the markup of inline references to bibliographic
    > > entries, I wonder whether it would stretch the standard too far to
    > > interpret a linkend in a citetitle as pointing to a bibliographic
    > > reference and process it as though it were a biblioref immediately
    > > following the citetitle. So, for example,
    > >
    > > <citetitlef pubwork=“book” linkend=“ref.stayton2007”>DocBook XSL: The
    > Complete Guide</citetitle>
    > >
    > > would be interpreted as equivalent to <citetitle
    > > pubwork=“book”>DocBook XSL: The Complete Guide</citetitle><biblioref
    > > linkend=“ref.stayton2007”/>
    >
    > That doesn’t seem unreasonable to me. What I tend to do myself, however,
    > is just the following:
    >
    > <biblioref linkend="ref.stayton2007"/>
    >
    > Which I then render inline as the title from the bibliography entry with
    > whatever styling seems appropriate. Saves me from having to type the
    > titles each time.
    >
    > > But, to take it a step further, how about interpreting <citetitle
    > > pubwork=“book” linkend=“ref.stayton2007”/> the same way, but pulling
    > > the title from the referenced biblioentry/bibliomixed element when the
    > > citetitle element is empty.
    > >
    > > Any thoughts?
    >
    > That’s what biblioref is for? :-)
    >
    > Be seeing you,
    > norm
    >
    > --
    > Norman Tovey-Walsh <ndw@nwalsh.com>
    > https://nwalsh.com/
    >
    > > Next to knowing when to seize an opportunity, the most important thing
    > > in life is to know when to forego an advantage.--Benjamin Disraeli
    >



  • 4.  Re: [docbook-apps] Bibliographic styling

    Posted 05-23-2020 18:05
    > Would it be possible to step back a level and work on it in combination
    > with CSL? https://citationstyles.org/ That way, it would not just be
    > limited to CMOS. (Although having CMOS would be a major bonus for me.)
    > The Github repo for the CSL styles are
    > https://github.com/citation-style-language/styles
    > There are a few on that list I would find extremely helpful.

    Oh, yes! That definitely looks promising!

    Be seeing you,
    norm

    --
    Norman Tovey-Walsh <ndw@nwalsh.com>
    https://nwalsh.com/

    > Westheimer's Discovery: A coupla months in the laboratory can save a
    > coupla hours in the library.



  • 5.  Re: [docbook-apps] Bibliographic styling

    Posted 05-24-2020 17:18
    > limited to CMOS. (Although having CMOS would be a major bonus for me.)
    > The Github repo for the CSL styles are
    > https://github.com/citation-style-language/styles
    > There are a few on that list I would find extremely helpful.

    I spent a few hours today poking at it and filed about a half dozen
    bugs. I think it’s probably doable; I plan to spend a little more time
    on it tomorrow, but no promises beyond that.

    Be seeing you,
    norm

    --
    Norman Tovey-Walsh <ndw@nwalsh.com>
    https://nwalsh.com/

    > Wandering in a vast forest at night, I have only a faint light to guide
    > me. A stranger appears and says to me: "My friend, you should blow out
    > your candle in order to find your way more clearly." This man is a
    > theologian.--Diderot



  • 6.  Re: [docbook-apps] Bibliographic styling

    Posted 05-25-2020 01:39
    Hi Peter,

    Looks interesting. I’ve poked around some and have a high-level, but possibly inaccurate idea of how this might work.

    Is the following correct?

    - CSL encodes the details of how a particular style works. It provides a machine readable set of instructions that can be used by a processor to generate output that follows a particular citation style.

    - To use CLS with DocBook, you could write a stylesheet that would take a biblioentry and format it based on the contents of a particular CSL file. You might do that as a pre-processor and convert biblioentry into bibliomixed, or you could convert directly from biblioentry into fo, html, etc.

    - Or, at least for HTML, you could convert a biblioentry into CSL-JSON and convert it to HTML with citeproc-js or pandoc-citeproc. I haven’t tried out citeproc-js or pandoc-citeproc, so I could be way off on this one.

    So, am I in the right ballpark?

    Dick
    -------
    XML Press
    XML for Technical Communicators
    http://xmlpress.net
    hamilton@xmlpress.net



    > On May 23, 2020, at 05:43, Peter Fleck <peterfleck@gmail.com> wrote:
    >
    > Richard,
    >
    > Would it be possible to step back a level and work on it in combination with CSL? https://citationstyles.org/ That way, it would not just be limited to CMOS. (Although having CMOS would be a major bonus for me.)
    > The Github repo for the CSL styles are https://github.com/citation-style-language/styles
    > There are a few on that list I would find extremely helpful.
    >
    > Peter
    >
    > On Sat, 23 May 2020 at 12:43, Norman Tovey-Walsh <ndw@nwalsh.com> wrote:
    > Richard Hamilton <hamilton@xmlpress.net> writes:
    > > I’m thinking of taking on the task of creating a docbook
    > > customization, similar to the iso690 customization, to process
    > > bibliographic information in the Chicago Manual of Style format.
    > >
    > > Before I dive in head first, I thought I’d check with the group to see
    > > if anyone has already done that.
    >
    > I wonder if it would be possible to describe the format in some
    > declarative way and either derive the stylesheet from that or interpret
    > it?
    >
    > I looked briefly at doing that with BibTeX once, but that seemed a
    > little too challenging for the amount of free time that I have (which is
    > generally measured in negative numbers).
    >
    > > To streamline the markup of inline references to bibliographic
    > > entries, I wonder whether it would stretch the standard too far to
    > > interpret a linkend in a citetitle as pointing to a bibliographic
    > > reference and process it as though it were a biblioref immediately
    > > following the citetitle. So, for example,
    > >
    > > <citetitlef pubwork=“book” linkend=“ref.stayton2007”>DocBook XSL: The Complete Guide</citetitle>
    > >
    > > would be interpreted as equivalent to <citetitle
    > > pubwork=“book”>DocBook XSL: The Complete Guide</citetitle><biblioref
    > > linkend=“ref.stayton2007”/>
    >
    > That doesn’t seem unreasonable to me. What I tend to do myself, however,
    > is just the following:
    >
    > <biblioref linkend="ref.stayton2007"/>
    >
    > Which I then render inline as the title from the bibliography entry with
    > whatever styling seems appropriate. Saves me from having to type the
    > titles each time.
    >
    > > But, to take it a step further, how about interpreting <citetitle
    > > pubwork=“book” linkend=“ref.stayton2007”/> the same way, but pulling
    > > the title from the referenced biblioentry/bibliomixed element when the
    > > citetitle element is empty.
    > >
    > > Any thoughts?
    >
    > That’s what biblioref is for? :-)
    >
    > Be seeing you,
    > norm
    >
    > --
    > Norman Tovey-Walsh <ndw@nwalsh.com>
    > https://nwalsh.com/
    >
    > > Next to knowing when to seize an opportunity, the most important thing
    > > in life is to know when to forego an advantage.--Benjamin Disraeli




  • 7.  Re: [docbook-apps] Bibliographic styling

    Posted 05-25-2020 08:06
    Richard Hamilton <hamilton@xmlpress.net> writes:
    > Is the following correct?

    [ Not intending to speak for Peter… ]

    > - CSL encodes the details of how a particular style works. It provides
    > a machine readable set of instructions that can be used by a processor
    > to generate output that follows a particular citation style.

    Yep.

    > - To use CLS with DocBook, you could write a stylesheet that would
    > take a biblioentry and format it based on the contents of a particular
    > CSL file. You might do that as a pre-processor and convert biblioentry
    > into bibliomixed, or you could convert directly from biblioentry into
    > fo, html, etc.

    Also, yep.

    > - Or, at least for HTML, you could convert a biblioentry into CSL-JSON
    > and convert it to HTML with citeproc-js or pandoc-citeproc. I haven’t
    > tried out citeproc-js or pandoc-citeproc, so I could be way off on
    > this one.

    That might actually be the only short-term practical solution. I’ve
    filed a few bugs on the CSL spec and its test suite. Near as I can tell,
    what actually exists is a reference implementation (citeproc-js) and a
    specification that only incompletely describes the behavior of that
    implementation.

    I still might poke at a DocBook+CSL to HTML stylesheet, but my
    enthusiasm as waned significantly. A third party implementation of CSL
    is going to fail tests in the test suite. The specification is not going
    to reflect why those tests *should* pass, and the only recourse is going
    to be to reverse engineer the citeproc-js implementation (either
    literally or by making something that’s bug-compatible; in as much as I
    assert that an implementation that doesn’t conform to the specification
    is buggy). Kind of disappointing, really.

    Be seeing you,
    norm

    --
    Norman Tovey-Walsh <ndw@nwalsh.com>
    https://nwalsh.com/

    > The common excuse of those who bring misfortune on others is that they
    > desire their good.--Vauvenargues



  • 8.  Re: [docbook-apps] Bibliographic styling

    Posted 05-25-2020 20:19
    Hi Norm,

    That’s too bad.

    For the moment, I think I’ll back into the project by creating a set of biblioentry tests based on the existing bibliographies in XML Press books (they are currently all in bibliomixed form) and a set of examples from a book called Cite Right, which is a guide to a variety of citation styles, including Chicago, MLA, APA, and a bunch of others.

    In addition to having a good set of tests, that should also be a test to see if biblioentry is sufficient to express a wide range of types, especially newer forms that have evolved since biblioentry was created.

    If you, or anyone on the mailing list, have examples that I could add, I’ll be glad to take them.

    Dick
    -------
    XML Press
    XML for Technical Communicators
    http://xmlpress.net
    hamilton@xmlpress.net



    > On May 25, 2020, at 01:05, Norman Tovey-Walsh <ndw@nwalsh.com> wrote:
    >
    > Richard Hamilton <hamilton@xmlpress.net> writes:
    >> Is the following correct?
    >
    > [ Not intending to speak for Peter… ]
    >
    >> - CSL encodes the details of how a particular style works. It provides
    >> a machine readable set of instructions that can be used by a processor
    >> to generate output that follows a particular citation style.
    >
    > Yep.
    >
    >> - To use CLS with DocBook, you could write a stylesheet that would
    >> take a biblioentry and format it based on the contents of a particular
    >> CSL file. You might do that as a pre-processor and convert biblioentry
    >> into bibliomixed, or you could convert directly from biblioentry into
    >> fo, html, etc.
    >
    > Also, yep.
    >
    >> - Or, at least for HTML, you could convert a biblioentry into CSL-JSON
    >> and convert it to HTML with citeproc-js or pandoc-citeproc. I haven’t
    >> tried out citeproc-js or pandoc-citeproc, so I could be way off on
    >> this one.
    >
    > That might actually be the only short-term practical solution. I’ve
    > filed a few bugs on the CSL spec and its test suite. Near as I can tell,
    > what actually exists is a reference implementation (citeproc-js) and a
    > specification that only incompletely describes the behavior of that
    > implementation.
    >
    > I still might poke at a DocBook+CSL to HTML stylesheet, but my
    > enthusiasm as waned significantly. A third party implementation of CSL
    > is going to fail tests in the test suite. The specification is not going
    > to reflect why those tests *should* pass, and the only recourse is going
    > to be to reverse engineer the citeproc-js implementation (either
    > literally or by making something that’s bug-compatible; in as much as I
    > assert that an implementation that doesn’t conform to the specification
    > is buggy). Kind of disappointing, really.
    >
    > Be seeing you,
    > norm
    >
    > --
    > Norman Tovey-Walsh <ndw@nwalsh.com>
    > https://nwalsh.com/
    >
    >> The common excuse of those who bring misfortune on others is that they
    >> desire their good.--Vauvenargues




  • 9.  Re: [docbook-apps] Bibliographic styling

    Posted 05-25-2020 00:50
    Hi Norm,

    You’re exactly right. biblioref is the right element for this. I was so focused on citetitle that I missed that entirely:-).

    Dick
    -------
    XML Press
    XML for Technical Communicators
    http://xmlpress.net
    hamilton@xmlpress.net



    > On May 23, 2020, at 04:42, Norman Tovey-Walsh <ndw@nwalsh.com> wrote:
    >
    > Richard Hamilton <hamilton@xmlpress.net> writes:
    >> I’m thinking of taking on the task of creating a docbook
    >> customization, similar to the iso690 customization, to process
    >> bibliographic information in the Chicago Manual of Style format.
    >>
    >> Before I dive in head first, I thought I’d check with the group to see
    >> if anyone has already done that.
    >
    > I wonder if it would be possible to describe the format in some
    > declarative way and either derive the stylesheet from that or interpret
    > it?
    >
    > I looked briefly at doing that with BibTeX once, but that seemed a
    > little too challenging for the amount of free time that I have (which is
    > generally measured in negative numbers).
    >
    >> To streamline the markup of inline references to bibliographic
    >> entries, I wonder whether it would stretch the standard too far to
    >> interpret a linkend in a citetitle as pointing to a bibliographic
    >> reference and process it as though it were a biblioref immediately
    >> following the citetitle. So, for example,
    >>
    >> <citetitlef pubwork=“book” linkend=“ref.stayton2007”>DocBook XSL: The Complete Guide</citetitle>
    >>
    >> would be interpreted as equivalent to <citetitle
    >> pubwork=“book”>DocBook XSL: The Complete Guide</citetitle><biblioref
    >> linkend=“ref.stayton2007”/>
    >
    > That doesn’t seem unreasonable to me. What I tend to do myself, however,
    > is just the following:
    >
    > <biblioref linkend="ref.stayton2007"/>
    >
    > Which I then render inline as the title from the bibliography entry with
    > whatever styling seems appropriate. Saves me from having to type the
    > titles each time.
    >
    >> But, to take it a step further, how about interpreting <citetitle
    >> pubwork=“book” linkend=“ref.stayton2007”/> the same way, but pulling
    >> the title from the referenced biblioentry/bibliomixed element when the
    >> citetitle element is empty.
    >>
    >> Any thoughts?
    >
    > That’s what biblioref is for? :-)
    >
    > Be seeing you,
    > norm
    >
    > --
    > Norman Tovey-Walsh <ndw@nwalsh.com>
    > https://nwalsh.com/
    >
    >> Next to knowing when to seize an opportunity, the most important thing
    >> in life is to know when to forego an advantage.--Benjamin Disraeli