Opened 14 years ago

Closed 14 years ago

#2701 closed Feature Requests (fixed)

Quickbook docs on internal link may be misleading

Reported by: Paul A. Bristow Owned by: Daniel James
Milestone: Boost 1.39.0 Component: quickbook
Version: Boost 1.37.0 Severity: Cosmetic
Keywords: Quickbook link article Cc:

Description

The Quickbook docs on the really, really useful Anchor links says

You can link within a document using:

[link section_id.normalized_header_text The link text]

But don't you have to include the article name, in this case 'quickbook'?

as in

[def comments [link quickbook.syntax.comments Comments]]

I read the docs that you only need syntax.comments.

(I also note that the article name is actually always converted using the section rules, inserting _ to create a name but I don't se where this is explained.

I assumed (the cause of many foulups) that I could use the section syntax thus to choose my own name:

article My Book One - The Big Picture Manual : mybook1

This didn't seem to work - perhaps by design - but it might be useful to avoid really long names like my_book_one_-_the_big_ picture_manual.

It might also be helpful to tell people to look at the log file produced by Quickbook to find the full link address - it can get difficult when nested many sections deep.

(A brilliant tool, especially with Doxygenation!)

Change History (8)

comment:1 by Daniel James, 14 years ago

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.

in reply to:  1 comment:2 by Paul A. Bristow, 14 years ago

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).

comment:3 by Daniel James, 14 years ago

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.

comment:4 by Paul A. Bristow, 14 years ago

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).

comment:5 by Daniel James, 14 years ago

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).

comment:6 by Daniel James, 14 years ago

Owner: changed from Eric Niebler to Daniel James
Status: new → assigned

comment:7 by Daniel James, 14 years ago

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

Refs #1213, #2701

comment:8 by Daniel James, 14 years ago

Resolution: → fixed
Status: assigned → closed

(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.

........

Note: See TracTickets for help on using tickets.