Bug 104804 - Help on "Export Bookmarks" and help on "Export bookmarks as named destinations" is not clear enough
Summary: Help on "Export Bookmarks" and help on "Export bookmarks as named destination...
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
Inherited From OOo
Hardware: All All
: medium enhancement
Assignee: Not Assigned
URL:
Whiteboard: target:7.6.0
Keywords: needsDevAdvice
Depends on:
Blocks: PDF-Export
  Show dependency treegraph
 
Reported: 2016-12-20 05:49 UTC by crun
Modified: 2023-02-28 01:03 UTC (History)
8 users (show)

See Also:
Crash report or crash signature:


Attachments
Small file that I would expect to contain named destinations (10.98 KB, application/vnd.oasis.opendocument.text)
2016-12-21 03:35 UTC, crun
Details
Python file that lists named destinations.... (5.00 KB, text/plain)
2016-12-21 03:41 UTC, crun
Details
PDF file with OK result (10.98 KB, application/vnd.oasis.opendocument.text)
2016-12-31 13:13 UTC, Buovjaga
Details
Test file with LO bookmarks added (11.21 KB, application/vnd.oasis.opendocument.text)
2017-01-07 21:25 UTC, crun
Details
odt file with <text:bookmark/> (5.57 KB, application/vnd.oasis.opendocument.text)
2017-11-23 12:33 UTC, Jos van den Oever
Details
pdf file created from nd.odt with named destinations (27.18 KB, application/pdf)
2017-11-23 12:33 UTC, Jos van den Oever
Details

Note You need to log in before you can comment on or make changes to this bug.
Description crun 2016-12-20 05:49:51 UTC
Description:
There are no named destinations in PDF.

Named destinations are the hayperlink targets for url sections (ie #xxx)
www.abc.com/some_pdf.pdf#asection

The Export as PDF -> PDFOptions dialog -> Links tab -> Export bookmarks as named destinations
is checked. Presumably this is supposed to make all the bookmarks be named destinations



Steps to Reproduce:
1. export as PDF
2.
3.

Actual Results:  
No named destinations

Expected Results:
named destinations for all bookmarks and table of contents entries


Reproducible: Always

User Profile Reset: No

Additional Info:


User-Agent: Opera/9.80 (Windows NT 6.1) Presto/2.12.388 Version/12.18
Comment 1 crun 2016-12-21 03:35:28 UTC
Created attachment 129831 [details]
Small file that I would expect to contain named destinations
Comment 2 crun 2016-12-21 03:41:56 UTC
Created attachment 129832 [details]
Python file that lists named destinations....

I think acrobat pro will display them, otherwise use this to list them all.

usage: python ListNamedDestinations.py SomePDFFile.pdf
Comment 3 Buovjaga 2016-12-31 13:13:13 UTC
Created attachment 130055 [details]
PDF file with OK result

Note that you have 0 bookmarks in your file. Check it with the Navigator.

Yet, even if I do not tick any checkboxes in PDF dialog Links tab, I do get the Sec1 and Sec2 in the index of the PDF (checked with Okular).

Arch Linux 64-bit, KDE Plasma 5
Version: 5.4.0.0.alpha0+
Build ID: fc0d4e6bc43d5f982452df07930f5ecf5927ad22
CPU Threads: 8; OS Version: Linux 4.8; UI Render: default; VCL: kde4; 
Locale: fi-FI (fi_FI.UTF-8); Calc: group
Built on December 31st 2016
Comment 4 crun 2017-01-07 01:00:40 UTC
Thanks B. 
You have attached the ODT, not PDF. When I try exporting it to PDF I don't get any nameddests


What I expect is that TOC entries which appear in the PDF-Bookmarks sidebar, would also be PDF-NamedDestinations.
Note that the PDF-bookmarks (the bookmarks/index sidebar are not the same as NamedDestinations, and there is no way to jump to them from the URL (blindingly stupid though that is)


Madar has put my NamedDestination lister online here: 

https://pdfresizer.com/list-named-destinations

Can you see if you actually get NamedDestinations when you try your PDF file?
Comment 5 crun 2017-01-07 01:02:06 UTC Comment hidden (obsolete)
Comment 6 Buovjaga 2017-01-07 10:59:25 UTC
(In reply to crun from comment #4)
> Thanks B. 
> You have attached the ODT, not PDF. When I try exporting it to PDF I don't
> get any nameddests

Yeah, sorry about the mistake.. I was also confused, as I had no actual idea, what the named destinations were in practice. I thought it would be enough to confirm the links are created in the PDF ToC. Apparently my ignorant guess was wrong.

But the point is: you are talking about the option "Export bookmarks as named destinations", while you have 0 bookmarks in your file. Bookmarks are created with Insert - Bookmark.

Do you want to turn this report into an enhancement request about having an option for turning ToC entries to named destinations?
Comment 7 crun 2017-01-07 21:25:53 UTC
Created attachment 130249 [details]
Test file with LO bookmarks added

This version has 2x LO bookmakrs added.
Comment 8 crun 2017-01-07 21:38:47 UTC
I added LO bookmarks - still no named destinations.

So it does definitely appear to be a bug.

The help says this, which I interpret as meaning the ToC entries
---
"Export bookmarks

Select to export bookmarks of Writer documents as PDF bookmarks. Bookmarks are created for all outline paragraphs (Tools - Outline Numbering) and for all table of contents entries for which you did assign hyperlinks in the source document."

----

But YES, if the LO intention was only to export LO bookmarks, then a feature request for automatically making NamedDestinations from ToC / PDF bookmarks is needed.

In that case the wording / tooltip needs to be changed to remove the ambiguity between LO book marks and PDF bookmarks
"Export LibreOffice bookmarks as Named Destinations"
And the help should be edited also, as well as provinding an explanation of NamedDestinations. (I would be happy to do this - better see if it is a wiki and I can just do it)

Note that the L.O bookmarks don't appear in the PDF bookmarks or ToC. What are they supposed to be for?
Comment 9 Buovjaga 2017-01-07 22:00:19 UTC
The documentation is here: https://help.libreoffice.org/Common/Export_as_PDF#Export_bookmarks_as_named_destinations

It says:
"The bookmarks (targets of references) in PDF files can be defined as rectangular areas. Additionally, bookmarks to named objects can be defined by their names. Enable the checkbox to export the names of objects in your document as valid bookmark targets. This allows you to link to those objects by name from other documents."

Frankly, I don't understand it. I tried creating some shapes in Writer, then Format - Name to give them names (they show in the Navigator), but there is no way I can *insert a bookmark pointing to them*. The named objects also do not magically create "named destinations" as proven by the pdfresizer.com test.

I was also unable to "link to those objects by name from other documents" - Insert - Link - Target in document does not show the named drawing shapes in the list.

I have to consult some gurus.

One thing is clear: the documentation needs improvement.
Comment 10 Xisco Faulí 2017-11-01 23:10:10 UTC
@Buovjaga, Any change the documentation can be improved here? Should a different issue be created?
Comment 11 Buovjaga 2017-11-02 13:33:27 UTC
(In reply to Xisco Faulí from comment #10)
> @Buovjaga, Any change the documentation can be improved here? Should a
> different issue be created?

Not until we get feedback on how this stuff actually works.
Comment 12 Jos van den Oever 2017-11-23 12:30:14 UTC
An ODF with <text:bookmark text:name="Test_2"> that is exported to PDF with 'Export bookmarks as named destinations' will get a named destination 'Test5F2'. The character '_' is changed to '5F'.

The named destinations in PDF files can be investigated with qpdf.

qpdf --qdf --object-streams=disable in.pdf out.pdf

This gives e.g.:

```
%% Original object ID: 44 0
1 0 obj
<<
  /Dests 3 0 R
...
%% Original object ID: 29 0
3 0 obj
<<
  /Test5F1 [
    6 0 R
    /XYZ
    56.7
    773.1
    0
  ]
  /Test5F15F1 [
    6 0 R
    /XYZ
    56.7
    736.2
    0
  ]
```

The destinations that LO writes out are points on pages (/XYZ). One could point to rectangles by using /FitR instead of /XYZ. Such a rectangle cannot span page boundaries.
Comment 13 Jos van den Oever 2017-11-23 12:33:01 UTC
Created attachment 137940 [details]
odt file with <text:bookmark/>

Converting this file to PDF with the option to convert bookmarks to named destinations will create named destinations in the PDF.
Comment 14 Jos van den Oever 2017-11-23 12:33:37 UTC
Created attachment 137941 [details]
pdf file created from nd.odt with named destinations
Comment 15 Jos van den Oever 2017-11-23 12:40:15 UTC
There is no need to convert '_' in a bookmark name to 5F. In PDF 'The name may include any regular characters, but not delimiter or white-space  characters  (see  
Section  3.1,  “Lexical  Conventions”).'
Comment 16 Jos van den Oever 2017-11-23 17:02:20 UTC
LibreOffice can already write \FitR.

https://cgit.freedesktop.org/libreoffice/core/tree/vcl/source/gdi/pdfwriter_impl.cxx#n3699
https://cgit.freedesktop.org/libreoffice/core/tree/vcl/source/gdi/pdfwriter_impl.cxx#n5559

The destination name is indeed escaped. I cannot really follow the reasoning in the comment of that function.

https://cgit.freedesktop.org/libreoffice/core/tree/vcl/source/gdi/pdfwriter_impl.cxx#n638
Comment 17 Cor Nouws 2017-11-23 17:43:24 UTC
Hi Crun,

thanks for helping with this issue.

(In reply to crun from comment #8)

> But YES, if the LO intention was only to export LO bookmarks, then a feature
> request for automatically making NamedDestinations from ToC / PDF bookmarks
> is needed.

If you expect TOC entries, i.e. the headings in a file to be Named Destinations too, then yes.

As Jos pointed out, Named Destinations are created. But only from the bookmarks (to names objects). And the resulting Named Destinations are not visible as bookmark in a PDF reader side panel, since it are destinations "to link to those objects by name from other documents."

> In that case the wording / tooltip needs to be changed to remove the
> ambiguity between LO book marks and PDF bookmarks
> "Export LibreOffice bookmarks as Named Destinations"

What tooltip, please? What is the wording and what would you suggest?

> And the help should be edited also, as well as provinding an explanation of
> NamedDestinations. 

What would you propose to improve in https://help.libreoffice.org/Common/Export_as_PDF#Export_bookmarks_as_named_destinations ?
Comment 18 crun 2017-11-28 00:27:58 UTC Comment hidden (obsolete)
Comment 19 Jean-Baptiste Faure 2018-06-19 19:22:46 UTC Comment hidden (obsolete)
Comment 20 QA Administrators 2019-01-11 15:21:46 UTC Comment hidden (obsolete)
Comment 21 Cor Nouws 2019-01-13 17:53:51 UTC
(In reply to Cor Nouws from comment #17)

> What would you propose to improve in
> https://help.libreoffice.org/Common/
> Export_as_PDF#Export_bookmarks_as_named_destinations ?

I think both help on Export Bookmarks (tab General, see comment 8) and help on export bookmarks as named destinations (tab Links - see comment 17) can be improved.

Change summary from 
  TOC entries are not exported as Named Destinations in PDF
to
  help on Export Bookmarks and help on export bookmarks as named destinations is not clear enough
Comment 22 sdc.blanco 2023-02-21 15:02:52 UTC
(In reply to Cor Nouws from comment #21)
> I think both help on Export Bookmarks (tab General, see comment 8) 
Command option name changed to "outline" with bug 133403 

Help addressed partly in: https://gerrit.libreoffice.org/c/help/+/104595 for bug 128837

but I believe the entry in [1] still needs improvement.

The text says:

   Select to export bookmarks of Writer documents as PDF bookmarks. 
   Bookmarks are created for all outline paragraphs (Tools - Chapter Numbering) 
   and for all table of contents entries for which you did assign hyperlinks in 
   the source document.

[1] https://help.libreoffice.org/7.6/en-US/text/shared/01/ref_pdf_export_general.html

Problems:
1. First "bookmarks" in first sentence probably should be changed, but to what?
2. Second sentence:  Add "PDF" in front of "bookmarks"
3. change "outline paragraphs" to "headings".

Are there other changes?  
If I can get reliable information, then I will make the patch.

> help on export bookmarks as named destinations (tab Links - see comment 17) 
Addressed in bug 150164


(should needsDevAdvice still be in Keywords?)
Comment 23 sdc.blanco 2023-02-27 11:22:20 UTC
@gabriel -- sorry to bother you, but may I draw on your expertise again in revising this help entry for "Export outlines" for PDF export in [1]?  Here is the text, and comment 22 identifies three "problems" with the text. But maybe there are other problems, or additional information that is important to indicate? Thanks.

   Select to export bookmarks of Writer documents as PDF bookmarks. 
   Bookmarks are created for all outline paragraphs (Tools - Chapter Numbering) 
   and for all table of contents entries for which you did assign hyperlinks in 
   the source document.

[1] https://help.libreoffice.org/7.6/en-US/text/shared/01/ref_pdf_export_general.html
Comment 24 gabriel.crabbe 2023-02-27 21:02:53 UTC
(In reply to sdc.blanco from comment #22)
> 1. First "bookmarks" in first sentence probably should be changed, but to what?

If the help text is correct, and "all table of contents entries (for which you did assign hyperlinks)" are exported in addition to headings, perhaps "table of content entries" is the most accurate description, as they include headings. You can then add the "for which you did assign hyperlinks" qualifier (which, to be honest, I did not understand) in the body.

> 2. Second sentence:  Add "PDF" in front of "bookmarks"

The preferred nomenclature in the PDF Reference is "outline" (singular: "outline item"), probably to avoid any confusion with the term "bookmarks" (although it is also accepted). Please consider using "outline" here, especially since "bookmarks" means something entirely different in LO, but  "outline" doesn't.

> 3. change "outline paragraphs" to "headings".

"headings" is good.
Comment 25 sdc.blanco 2023-02-27 23:08:33 UTC
(In reply to gabriel.crabbe from comment #24)
Thanks for helping me to untangle the text! I can see now that the solution is simple.

I will write out the explanations here (to document the change). 

The help page should be:

---------------

Export outlines

 Select to export all headings in Writer documents as PDF bookmarks. 

---------------------

1. Reason to use "bookmarks":  As an empirical fact, LO headings appear in Adobe Reader's in the "Bookmarks" section of the Reader's Navigation Pane, so it seemed useful (for naïve users like me) to have this consistency in the terminology between Reader and the LO help. 

2. Reason why the part about Table of Contents and hyperlinks is dropped: The "Export outlines" option has no influence in this case, so this information is irrelevant. Furthermore, hyperlinks (whether from Table of Contents or from simply inserting a hyperlink seem to be exported to PDF documents, without having to set any options).  (I could not find this information documented anywhere.  Maybe it is worth mentioning somewhere?)
Comment 26 Commit Notification 2023-02-28 00:39:20 UTC
Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/8d94705d5baaed4be8d2521d9caf7510ff5d9d76

tdf#104804 - clarify explanation for "export outlines"
Comment 27 sdc.blanco 2023-02-28 01:03:03 UTC
(In reply to sdc.blanco from comment #25)
> Maybe it is worth mentioning somewhere?
https://git.libreoffice.org/help/commit/2e037f2dbf9c7d93ce020ca1709c581624c75fbd

Tooltip and Extended tip for "Export outlines" were updated recently, and refer appropriately to headings. They also mention Table of Contents; will leave this convenient fiction in the tips.

Thanks to Gabriel Crabbe for technical expertise.

Closing as FIXED.  If further adjustments are needed, then they can be sent to this ticket.