Boost C++ Libraries: Ticket #2701: Quickbook docs on internal link may be misleading

Daniel James — Fri, 30 Jan 2009 18:59:20 GMT

FWIW, you can can give an article id by writing something like:

[article My Book One - The Big Picture Manual
    [quickbook 1.4]
    [id mybook1]
    [dirname mybook1]
]

This is documented in the Document section.

Paul A. Bristow — Sat, 31 Jan 2009 10:35:20 GMT

Replying to danieljames:

FWIW, you can can give an article id by writing something like:
[article My Book One - The Big Picture Manual
    [quickbook 1.4]
    [id mybook1]
    [dirname mybook1]
]
This is documented in the Document section.

Oh Dear not RFTM again :-(

But I'm not sure things are quite right.

If I create an article ID thus

[article Plot in SVG

[quickbook 1.4] [id SVG_plot]

...

I get (in the log)

Writing plot_in_svg/howtouse.html for section(plot_in_svg.howtouse)

so it is using the title, Plot in SVG converted using the rules to "plot_in_svg"

that than the expected "svg_plot" from the id.

Am I still doing something silly?

(And my 1st 'complaint' about documenting the use of this in links stands).

Daniel James — Sat, 31 Jan 2009 11:44:58 GMT

Oh Dear not RFTM again :-(

I wouldn't say that, it's not that easy to find. I think the quickbook documentation could do with a little tutorial that introduces these concepts. But that's for another day.

I get (in the log)

Writing plot_in_svg/howtouse.html for section(plot_in_svg.howtouse)

It works for me... For this quickbook file:

[article Plot in SVG
  [quickbook 1.4]
  [id SVG_plot]
]
Test

Which produces this boostbook:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<article id="SVG_plot" name="Plot in SVG" dirname="SVG_plot" last-revision="$Date: 2009/01/31 10:37:36 $"
 xmlns:xi="http://www.w3.org/2001/XInclude">
  <articleinfo>
  </articleinfo>
  <title>Plot in SVG</title>
  <para>
    Test
  </para>
</article>

Note that id and dirname are both SVG_plot.

If you still still can't get it to work, then I guess that's a new ticket.

(And my 1st 'complaint' about documenting the use of this in links stands).

Yes, I don't have the time to deal with it at the moment. That's why I didn't accept the ticket.

Paul A. Bristow — Mon, 02 Feb 2009 11:03:08 GMT

OK fine - this is not urgent, but when you have nothing better to do ;-)

<?xml version="1.0"?> <!DOCTYPE article PUBLIC "-OASISDTD DocBook XML V4.2EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <article xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" id="SVG_plot" name="SVG Plot Manual document title" dirname="SVG_plot" rev:last-revision="$Date: 2009/02/02 10:46:37 $">

has the title, ID and dirname as we both expect.

But am I wrong to be surprised that the section id comes from the title, and not from the id

<title>SVG Plot Manual document title</title> <section id="svg_plot_manual_document_title.howtouse">

<title><link linkend="svg_plot_manual_document_title.howtouse"> How To Use This

Perhaps this is a feature?

(I'm also uncertain (but that's not uncommon) what dirname is intended for).

Daniel James — Mon, 02 Feb 2009 11:30:39 GMT

That looks like a bug to me. I'll need to see the quickbook file to work out what's going on. Can you either create a new ticket and attach it (or a simplified version).

(I'm also uncertain (but that's not uncommon) what dirname is intended for).

I just looked it up, and I've been using it incorrectly myself. It's only valid boostbook for a library anyway, so that's another bug. It's used to indicate the source location of a library. I've created a ticket (#2711).

owner, status changed

Daniel James — Sun, 22 Feb 2009 16:10:44 GMT

owner changed from Eric Niebler to Daniel James
status new → assigned

Daniel James — Sun, 01 Mar 2009 14:16:46 GMT

(In [51508]) Try to make anchor and link usage a little clearer.

Refs #1213, #2701

status changed; resolution set

Daniel James — Sat, 14 Mar 2009 11:42:43 GMT

status assigned → closed
resolution → fixed

(In [51774]) Merge most of the recent changes to quickbook and boostbook.

Left out doxygen changes: [51323],[51324],[51680] And a quickbook change which might be a breaking change: [51403]

Fixes #1977, #1170, #1213, #2701. Refs #2153, #2771.

Merged revisions 51268-51269,51319-51321,51370-51372,51388-51389,51401-51402,51405-51406,51508,51647,51696 via svnmerge from https://svn.boost.org/svn/boost/trunk

........

r51268 | johnmaddock | 2009-02-16 10:39:18 +0000 (Mon, 16 Feb 2009) | 1 line

Add default path for callouts.

........

r51269 | johnmaddock | 2009-02-16 10:40:26 +0000 (Mon, 16 Feb 2009) | 1 line

Add preliminary HTMLHelp support.

........

r51319 | danieljames | 2009-02-18 21:22:37 +0000 (Wed, 18 Feb 2009) | 1 line

Remove long out of date warning.

........

r51320 | danieljames | 2009-02-18 21:23:13 +0000 (Wed, 18 Feb 2009) | 1 line

Write out the quickbook options when the file is missing.

........

r51321 | danieljames | 2009-02-18 21:23:35 +0000 (Wed, 18 Feb 2009) | 1 line

Add default path for callouts to xhtml.

........

r51370 | danieljames | 2009-02-21 18:50:00 +0000 (Sat, 21 Feb 2009) | 4 lines

Regenerate boostbook reference documentation and merge with existing documentation.

Ref #2153

........

r51371 | danieljames | 2009-02-21 18:50:14 +0000 (Sat, 21 Feb 2009) | 1 line

Fix links in standalone boostbook documentation.

........

r51372 | danieljames | 2009-02-21 18:50:25 +0000 (Sat, 21 Feb 2009) | 3 lines

Change license in boostbook docs to boost license.

Douglas Gregor is listed in the blanket permissions file.

........

r51388 | danieljames | 2009-02-22 11:54:01 +0000 (Sun, 22 Feb 2009) | 1 line

This DTD isn't stable, so I'm calling it a 'development' version. Which is probably wrong, but there you go.

........

r51389 | danieljames | 2009-02-22 11:54:18 +0000 (Sun, 22 Feb 2009) | 2 lines

Support the alt tag in headername and macroname. Also make headername and macroname valid. Refs #1977

........

r51401 | danieljames | 2009-02-22 23:47:51 +0000 (Sun, 22 Feb 2009) | 8 lines

Add a purpose for macroname, headername, enumname, globalname.

Ref #2153: There's still no documentation for methodname and classname. These are actually defined in the docbook DTD for a different purpose so I'm not sure how to deal with them.

http://www.docbook.org/tdg/en/html/methodname.html http://www.docbook.org/tdg/en/html/classname.html

........

r51402 | danieljames | 2009-02-22 23:48:37 +0000 (Sun, 22 Feb 2009) | 7 lines

Generate slightly more valid boostbook.

For document types other than library:

Don't generate name or dirname for document types.
Put title before document info.

Ref #2771

........

r51405 | danieljames | 2009-02-22 23:49:21 +0000 (Sun, 22 Feb 2009) | 3 lines

Print out unexpected characters as errors.

Ref #1170

........

r51406 | danieljames | 2009-02-22 23:49:36 +0000 (Sun, 22 Feb 2009) | 1 line

Better handling of errors without line numbers.

........

r51508 | danieljames | 2009-03-01 14:16:44 +0000 (Sun, 01 Mar 2009) | 3 lines

Try to make anchor and link usage a little clearer.

Refs #1213, #2701

........

r51647 | danieljames | 2009-03-08 09:45:51 +0000 (Sun, 08 Mar 2009) | 1 line

Display text purposes in function reference.

........

r51696 | johnmaddock | 2009-03-11 10:22:42 +0000 (Wed, 11 Mar 2009) | 1 line

Set margins to 0pt so they line up with surrounding text rather than appearing outside it - prevents margins from overlapping other content.

........