Not logged in. · Lost password · Register
Forum: General Help and Support Plugins RSS
ePub Extension  Link/Bookmarks to Titles
Links/Bookmarks to titles
Avatar
rgleason #1
Member since Sep 2016 · 272 posts
Group memberships: Members
Show profile · Link to this post
Subject: ePub Extension  Link/Bookmarks to Titles
First of all, I would like to report that this ePub Extension is superb. We now have a very useful ePub User Manual for OpenCPN with a fully operational Table of Contents which matches the  IndexMenu "sidebar"  (I had to recreate this manually in Calibre, but it was not very difficult to do.  Sometime it would be nice if it could be made automatically.) This manual is 23mb and can be converted to PDF as well and then optimized for the web to be compressed to 23mb as well.  Epub Extension is the first time we have been able to create good documentation from Dokuwiki without a huge headaches and excessive time laboriously editing html.  Thank you Myron and the rest of the Team!

There several aspects that need some improvement IMHO:
1. Automatic generation of TOC either with the use of a special TOC page, or by using the Indexmenu sidekick page.
2. Handling of # Link/Bookmarks to Titles  (for #title links to within a namespace and #title links to other namespaces.

I am finding that these types of Dokuwiki links do not translate properly.
I had over 500 error/warnings on a recent conversion and the majority of the problems were related to the use of "#" in either the relative or absolute path form.

Referencing other pages, and including a Title

as in https://opencpn.org/wiki/dokuwiki/doku.…?id=opencpn:open…
**__[[opencpn:opencpn_user_manual:options_setting:display|The Display]]__ ** \\
 //[[opencpn:opencpn_user_manual:options_setting:display#general|General]]\\
 [[opencpn:opencpn_user_manual:options_setting:display#units|Units]]\\
 [[opencpn:opencpn_user_manual:options_setting:display#advanced|Advanced]]//\\
It seems to me that the ePub Extension when converting to epub, should inserting bookmarks at the proper location to make these links work properly.  Please see the quote and reference below about the use of # and bookmarks in epub.  Thanks. Rick


Referencing the same page and including a Title

As in https://opencpn.org/wiki/dokuwiki/doku.…?id=opencpn:open… Scroll down to Links for the example.
  - [[#hardware_installation|Hardware installation]]
  - [[#software_requirements|Software installation]]
  - [[#basic_operation|Basic operation]]
  - [[#view_menu|Target trails]]
  - [[#ebl_vrm|Cursor, EBL and VRM]]
  - [[#guard_zone|Guard zones]]
  - [[#timed_transmit|Timed transmit]]
In this case, where the link is from within the same page, in order to get it to work I must change the code to use the full pages pathname.  For example:

  - [[opencpn:opencpn_user_manual:plugins:ais_radar:br24_radar#hardware_installation|Hardware installation]]

(This may be changing in epub, as there was a fix noted for calibre to this effect, but it does not seem to be working and I have had to use the full pathname.) I have updated to the most current Calibre 3.31 [07 Sep, 2018]  actually I think it is 3.39 now.)
This is from an ePub tutorial 
http://www.jedisaber.com/eBooks/formatsource.shtml

Making Links to a specific part of a fie:

What if you want to want to link to a specific part of a file? Taking our example above, let's say chap01.xhtml has a reference to apple trees. Let's say chap02.xhtml has details on different kinds of fruit trees, each in it's own section, but all in the same XHTML file. Let's also say we want to provide a link in Chapter 1 that will jump straight to the section on apple trees in Chapter Two. If we just put a link in using the information in the above section, it will just take us to the beginning of Chapter 2, not to the specific section we want. How do we do that?

We have to do two things:

    add a bookmark to the code in chap02.xhtml where we want to link too.
    modify our link to point to not only the page, but the bookmark

Adding a bookmark:

A bookmark in HTML is just what it sounds like. A small hunk of code that we can use to make a hyperlink jump to the exact part of an HTML file that we want it to. In our example, we would add the following code to chap02.xhtml just above where we want the link to go to:

<a name="AppleTrees"></a>

You'll note that a HTML bookmark uses the same markup tag as the hyperlink, but with a different identifier and missing all the linky bits. Note that the link text ("AppleTrees", in this case, can be anything you want.)

To make our link jump right to the section on Apple Trees, make the link in chap01.xhtml look like this:

<a href="chap02.xhtml#AppleTrees">Link Text</a>

Basically, you add #LinkName to the the URL in your hyperlink. The part after the # sign has to match the text you have in the Name attribute of your bookmark. Now when you click (or tap) the link in Chapter 1, it will not only link you to Chapter 2, but to the right spot in Chapter 2.

Note: If you want to link to a bookmark in the same file (for example, if you want a link in Chapter 1 to go to another section in Chapter 1) put a bookmark where you want the link to go to, and make the link look like this:

<a href="#BookmarkName">Link Text</a>

We leave out the filename because we're just going to a different place in the same file, so all that's required is the bookmark name.

This post was edited on 2018-09-10, 19:12 by rgleason.
Avatar
turnermm (Moderator) #2
Member since Oct 2009 · 4673 posts · Location: Canada
Group memberships: Global Moderators, Members, Super Mods
Show profile · Link to this post
2. Handling of # Link/Bookmarks to Titles
This was the intention of the last update: line 296. It worked in my tests, but with internal links only.

- [[#hardware_installation|Hardware installation]]
haven't looked at this

for #title links to within a namespace and #title links to other namespaces.
Don't know what this means.

<a name="AppleTrees"></a>
This is not a feature of DokuWiki, but a plugin insertion: https://www.dokuwiki.org/plugin:anchor.  Not all plugins are supported.

I suggested an alternative to indexmenu:
    https://mturner.org/devel/playground/links_t
Myron Turner
github: https://github.com/turnermm
plugins, templates: http://www.mturner.org/devel
Avatar
rgleason #3
Member since Sep 2016 · 272 posts
Group memberships: Members
Show profile · Link to this post
Subject: Links to Titles - both on the same page and to another page
Myron, Note:I have not tried the most recent Epub extension, that I just updated.
I have been using the results of the previous version and learning how to correct it using Calibre.
There are a number of important links to "Titles" in the text that are not working very well, perhaps partially because we are not using the appropriate namepace#Title link configurations in the original dokuwiki to achieve a successful result and partially because Epub may not be recognizing the links properly and outputting them.

Here is what I have been doing for about a week, changing all links in the EPUB book to conform to the following.

Hyperlinks to Titles within namespace/pages:

    For the Hyperlink:  <a href "#create_a_mark">Create a Mark</a>
    For the Heading: <h2 id="create_a_mark"> Create a Mark</h2>

Hyperlinks to Titles in other namespaces/pages:
    For the Hyperlink:  <a href="opencpn_opencpn_user_manual_options_setting_display.html#the_display">The Display</a>
    For the Heading: <h1 id="the_display" class="calibre5">The Display</h1> 

Which works in EPUB.



Please advise what the correct format should be for links to work properly when converted to EPUB by Epub Extension,
for
Hyperlinks to Titles within internal namespace/pages
Hyperlinks to Titles in other namespaces/pages

In the case of internal links to Titles is it preferred to just use 
 <a href "#create_a_mark">Create a Mark</a>  ?

In the case of external links to Titles in other namespace/pages is it preferred to use the full namespace?
<a href="opencpn_opencpn_user_manual_options_setting_display.html#the_display">The Display</a>

Will both of these translate properly with the Current Epub?

I'd like to go through the entire original online document and correct all of these so they will work when translated to Epub.
Thanks,
Avatar
turnermm (Moderator) #4
Member since Oct 2009 · 4673 posts · Location: Canada
Group memberships: Global Moderators, Members, Super Mods
Show profile · Link to this post
It will take me a while to check these out.  I'm afraid I can't answer off the top of my head, and right now I don't  have the time to  look into it.  When I get the time, I will get back to you. If you don't hear from me in a couple of weeks, ping me here on the list.
Myron Turner
github: https://github.com/turnermm
plugins, templates: http://www.mturner.org/devel
Avatar
rgleason #5
Member since Sep 2016 · 272 posts
Group memberships: Members
Show profile · Link to this post
Myron,

I am going to do some tests locally, to determine exactly what happens, and will report back here, ok. I should have done that myself, but I was pressed at the time I wrote too. Sorry.
Avatar
rgleason #6
Member since Sep 2016 · 272 posts
Group memberships: Members
Show profile · Link to this post
Dear Myron,

I am back at it with epub. I mistakenly deleted my epub text file on my local drive, so I am recreating it, and using epub to create and download an epub, that I load into Sigil and then use tools to fix and clean up Html, then clean up Epub, and then I check the links and I am finding many of the internal links showing as  Title[some number] for an external reference.
Why is the transition process treating these links as external when they should be internal?
   
Do you by any chance know why would this be happening? 
Is there a quick way to get these internal links to work properly?

Wish I could upload an image.
Avatar
turnermm (Moderator) #7
Member since Oct 2009 · 4673 posts · Location: Canada
Group memberships: Global Moderators, Members, Super Mods
Show profile · Link to this post
I don'tknow what's happening on your site, but I just test with the latest epub and it seems to be working as always.  It treats as external links local wiki pages which are not included in the epub book itself.
Myron Turner
github: https://github.com/turnermm
plugins, templates: http://www.mturner.org/devel
This post was edited 2 times, last on 2019-05-09, 18:11 by turnermm.
Avatar
rgleason #8
Member since Sep 2016 · 272 posts
Group memberships: Members
Show profile · Link to this post
Subject: epub for OpenCPN documentation
Myron, Thankyou.  As you know we are now using epub for OpenCPN documentation, having found it much easier to work with.

I am trying to find an easy way to create the hard coded pages that epub requires. Perhaps you have some suggestions.

From this TOC User Manual namespacee  https://opencpn.org/wiki/dokuwiki/d…?id=opencpn:toc&…
if I look at the page source we have all the information needed  (plus the excess html)

This has been generated by Indexmenu and we are using this format

%%{{indexmenu>:opencpn#4|msort nsort nojs skipns=/(^opencpn:developer_manual$|^opencpn:supplementary_software$|^opencpn:supplementary_hardware$|^opencpn:user_corner$|^opencpn:opencpn_user_manual:charts:advanced_chart_work$|^opencpn:opencpn_user_manual:charts:pilot_charts$|^opencpn:opencpn_user_manual:editors$|^opencpn:opencpn_user_manual:edit_user_manual$|^opencpn:opencpn_user_manual:gallery_boats$)/}}%%

The relevant part of the page source looks like this:

<li class="open"><div class="li"><a href="/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:getting_started" class="indexmenu_idx_head">Getting Started</a></div>

Do you know of an easy way to get it formatted like this for epub?

[[opencpn:opencpn_user_manual:getting_started|Getting Started]]

Maybe IndexMenu would be able do that in it's output, by having a trigger that would show the path & title in that format?  Then I could just highlight and copy the screen output and a special epub file would not have to be maintained through all the documentation changes. This list of pages could be made when we are going to publish.

What I actually need is something like to old dos "dir > filename.txt"

Who would I talk to about this possibility?  It would dovetail nicely with epub.

BTW we have just released OpenCPN version 5.0 and everyone is hard a work answering user questions and fixing bugs,  but the Dokuwiki documentation is still for v4.8.8. When the dust settles we are going to have to update the manual and hopefully package it differently.

One of the goals is to package separate smaller epub modules for documentation, and the second goal is to have a very stripped down "Basic Manual" that will ship with the software. To do this we need to place html on a github page (it will just be one, for the purpose of packaging). Is there a reasonable way to accomplish that from the Dokuwiki?  IE convert it to html and then publish to github?

Thank you for all your help and advice. It has always been right on the mark!

PS I've been using Sigil, but I understand the best process is to use Calibre and clean up the html and then bring it into Sigil and use their tools for html and epub, including the Table of Contents feature.  I've found what I think are recent Calibre changes to be more confusing but perhaps that will go away as I get back into it.
This post was edited 2 times, last on 2019-05-09, 22:29 by rgleason.
Avatar
turnermm (Moderator) #9
Member since Oct 2009 · 4673 posts · Location: Canada
Group memberships: Global Moderators, Members, Super Mods
Show profile · Link to this post
I'm afraid I'm not sure what you are asking.  And I'm not sure what this refers to:
the hard coded pages that epub requires

In what way hard coded and what do you mean by required?
Myron Turner
github: https://github.com/turnermm
plugins, templates: http://www.mturner.org/devel
Avatar
rgleason #10
Member since Sep 2016 · 272 posts
Group memberships: Members
Show profile · Link to this post
With epub, I need to have each page that I want to export in this fashion

[[opencpn:opencpn_user_manual:getting_started|Getting Started]]

one page after another. 

I consider that "hard coded", as compared to what indexmenu does, which uses the file structure and some specific directions to create a "dynamic on the fly" TOC.

Maybe I am thick. ..Say I just wanted it to export all pages from this namespace down to the bottom, even including [blank] pages?

[[opencpn:opencpn_user_manual|User Manual]]

Is there a command for a way to do that?
Is there a command to not include a namespace and namespaces below that?
Thinking about this situation, is there a command to exclude [blank] pages?
This post was edited on 2019-05-09, 22:52 by rgleason.
Avatar
turnermm (Moderator) #11
Member since Oct 2009 · 4673 posts · Location: Canada
Group memberships: Global Moderators, Members, Super Mods
Show profile · Link to this post
There is limited support for namespaces, probably not what you need: https://www.dokuwiki.org/plugin:epub#namespaces.

As for blank pages, if by that you mean empty pages, they do not exist in dokuwiki.  An empty page is removed.

Epub can't read indexmenu html, or any html, for that matter. 

If you need an enhanced table of contents, see: https://www.dokuwiki.org/plugin:epub#enhanced_table_of_con…
Myron Turner
github: https://github.com/turnermm
plugins, templates: http://www.mturner.org/devel
Avatar
rgleason #12
Member since Sep 2016 · 272 posts
Group memberships: Members
Show profile · Link to this post
In reply to post #10
Okay after recreating my earlier listing of each namespace with its title

[[opencpn:opencpn_user_manual|OpenCPN User Manual]]

[[opencpn:opencpn_user_manual:toc|Table of Contents]]
   [[opencpn:opencpn_user_manual:getting_started|Getting Started]]
       [[opencpn:opencpn_user_manual:getting_started:opencpn_installation|OpenCPN Installaton]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:windows|Windows]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:ubuntu_ppa|Ubuntu PPA]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:linux|Linux]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:fedora|Fedora]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:mac_os_x|MacOSx]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:orange_pi|Orange Pi]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:dedicated_marine_os|Dedicated Marine OS]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:raspberrypi_rpi2|RaspberryPi]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:android|Android]]
          [[opencpn:opencpn_user_manual:getting_started:opencpn_installation:release_history|Release Directory]]
       [[opencpn:opencpn_user_manual:getting_started:opencpn_first_use|OpenCPN First Use]]
       [[opencpn:opencpn_user_manual:getting_started:gps_setup|GPS Setup]]
       [[opencpn:opencpn_user_manual:getting_started:chart_installation|Chart Installation]]
       [[opencpn:opencpn_user_manual:getting_started:setting_option|Setting Options]]
       [[opencpn:opencpn_user_manual:getting_started:marks_and_routes|Marks and Routes]]
       [[opencpn:opencpn_user_manual:getting_started:touch_screen_tablets|Touch Screen Tablets]]
       [[opencpn:opencpn_user_manual:getting_started:help_fix_bugs|Help fix Bugs]]
   [[opencpn:opencpn_user_manual:getting_around|Getting Around]]
 and so on for pages, done completely manuallly

I tried this at the top, after reading the manual.

<epub:User Manual-2>
:opencpn:opencpn_user_manual:*

With this result


Directory: /home/szlhykiz/public_html/wiki/dokuwiki/data/pages/opencpn/opencpn_user_manual
Found following pages in :opencpn:opencpn_user_manual:* namespace:
Array
(
    [0] => :opencpn:opencpn_user_manual:toolbar_buttons
    [1] => :opencpn:opencpn_user_manual:toc_offline_user_manual_charts
    [2] => :opencpn:opencpn_user_manual:toc_offline_user_manual
    [3] => :opencpn:opencpn_user_manual:toc_offline_plugins_manual
    [4] => :opencpn:opencpn_user_manual:toc_offline_advanced_features
    [5] => :opencpn:opencpn_user_manual:toc
    [6] => :opencpn:opencpn_user_manual:terminology
    [7] => :opencpn:opencpn_user_manual:plugins
    [8] => :opencpn:opencpn_user_manual:options_setting
    [9] => :opencpn:opencpn_user_manual:menubar
    [10] => :opencpn:opencpn_user_manual:license_and_authors
    [11] => :opencpn:opencpn_user_manual:getting_started
    [12] => :opencpn:opencpn_user_manual:getting_around
    [13] => :opencpn:opencpn_user_manual:faq
    [14] => :opencpn:opencpn_user_manual:epub
    [15] => :opencpn:opencpn_user_manual:editors
    [16] => :opencpn:opencpn_user_manual:charts
    [17] => :opencpn:opencpn_user_manual:advanced_features
)
Saving namespace pages
Created following titles:
Array
(
    [0] => Toolbar Buttons
    [1] => Toc Offline User Manual Charts
    [2] => Toc Offline User Manual
    [3] => Toc Offline Plugins Manual
    [4] => Toc Offline Advanced Features
    [5] => Toc
    [6] => Terminology
    [7] => Plugins
    [8] => Options Setting
    [9] => Menubar
    [10] => License And Authors
    [11] => Getting Started
    [12] => Getting Around
    [13] => Faq
    [14] => Epub
    [15] => Editors
    [16] => Charts
    [17] => Advanced Features
)
processed: :opencpn:opencpn_user_manual:advanced_features
processed: :opencpn:opencpn_user_manual:charts
processed: :opencpn:opencpn_user_manual:editors
processed: :opencpn:opencpn_user_manual:epub
processed: :opencpn:opencpn_user_manual:faq


Which is great, but it does not seem to be going down to lower levels.

When I download the file and use Calibre I notice that internal links are still shown as  Name [174] for example. The link goes to a reference to an "internal page" which it should not as far as I understand. This used to work properly.

When I download the file and use Sigil, I notice that the internal links are still shown as Name [174] for example. Link goes to a reference to an internal page similar to these in the footnotes:

opencpn_opencpn_user_manual.html

[1] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:getting_started
[2] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:getting_around
[3] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:charts
[4] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:options_setting
[5] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:toolbar_buttons
[6] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:menubar
[7] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:plugins
[8] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:advanced_features
[9] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:terminology
[10] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:faq
[11] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:license_and_authors
[12] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:editors
[13] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:getting_started
[14] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:getting_around
[15] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:toolbar_buttons
[16] https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:opencpn_user_manual:menubar

I am wondering what I am doing wrong here.
Avatar
rgleason #13
Member since Sep 2016 · 272 posts
Group memberships: Members
Show profile · Link to this post
Now I am finding when I bring the 20mb epub result of this code:

<epub:User Manual-2>
:opencpn:opencpn_user_manual:*

direct into Sigil and I am prompted for fixing html which I did.
Then I used the epub fix tools and went to the first page, and the links all work properly.

Why are the links not working properly when each page is listed fully?
Avatar
turnermm (Moderator) #14
Member since Oct 2009 · 4673 posts · Location: Canada
Group memberships: Global Moderators, Members, Super Mods
Show profile · Link to this post
I don't understand your question, which may be perfectly clear to you who are working with it every day but not to me as an outsider.  What are the epub fix tools?  Are you talking about the admin panel? And what is meant by each page listed fully?  Where?
Myron Turner
github: https://github.com/turnermm
plugins, templates: http://www.mturner.org/devel
Close Smaller – Larger + Reply to this post:
Verification code: VeriCode Please enter the word from the image into the text field below. (Type the letters only, lower case is okay.)
Smileys: :-) ;-) :-D :-p :blush: :cool: :rolleyes: :huh: :-/ <_< :-( :'( :#: :scared: 8-( :nuts: :-O
Special characters:
Go to forum
Imprint
This board is powered by the Unclassified NewsBoard software, 20150713-dev, © 2003-2015 by Yves Goergen
Current time: 2019-07-17, 12:44:03 (UTC +02:00)