Modify

Opened 9 years ago

Closed 9 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!)

Attachments (0)

Change History (8)

comment:1 Changed 9 years ago by Daniel James

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.

comment:2 in reply to:  1 Changed 9 years ago by Paul A. Bristow

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 Changed 9 years ago by Daniel James

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 Changed 9 years ago by Paul A. Bristow

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 Changed 9 years ago by Daniel James

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 Changed 9 years ago by Daniel James

Owner: changed from Eric Niebler to Daniel James
Status: newassigned

comment:7 Changed 9 years ago by Daniel James

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

Refs #1213, #2701

comment:8 Changed 9 years ago by Daniel James

Resolution: fixed
Status: assignedclosed

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

........

Modify Ticket

Change Properties
Set your email in Preferences
Action
as closed The owner will remain Daniel James.
The resolution will be deleted.

Add Comment


E-mail address and name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.