Custom entry IDs in HTML export

Custom entry IDs in HTML export

[Daniel Clemente]

Hi, this may have been reported before; however I didn't find it in the FAQ.

  I would like to choose which ID each heading will have when they are exported to HTML. For instance, I want the table of contents to link to the anchor #tutorials instead of #sec-1.4.1. In this way, external links won't depend on the section ordering. It is also more expressive semantically.

  At the moment the best I know of is:

** TODO heading
#<<target>>

  This is exported as:
: <h3 id="sec-1.1"><a name="target" id="target"></a><span class="section-number-3">1.1</span> <span class="todo TODO"> TODO</span> heading </h3>

  But I want:
: <h3 id="target"><span class="section-number-3">1.1</span> <span class="todo TODO"> TODO</span> heading </h3>



  Since entries can already have IDs (I mean the property "ID", obtained by C-c l for instance), this could now be easier to implement. 
  As an extreme solution: If org-mode used exactly that ID to link to the entry, I wouldn't mind changing the entry ID overall in my files so that they have meaningful names instead of random data. Maybe I wouldn't even mind having an HTML ID called b9c1a93e-2af4-4a41-bfe3-8d2bd62c0614… (if it starts with a letter, it's still a valid ID).


  In case it's too complex to do this in org, do you know of some script to replace the IDs after export?


  Thanks,

Daniel

Re: Custom entry IDs in HTML export

[Carsten Dominik]

Hi Daniel,

On Mar 27, 2009, at 1:47 PM, Daniel Clemente wrote:

>
> Hi, this may have been reported before; however I didn't find it in  
> the FAQ.
>
>  I would like to choose which ID each heading will have when they  
> are exported to HTML. For instance, I want the table of contents to  
> link to the anchor #tutorials instead of #sec-1.4.1. In this way,  
> external links won't depend on the section ordering. It is also more  
> expressive semantically.
>
>  At the moment the best I know of is:
>
> ** TODO heading
> #<<target>>
>
>  This is exported as:
> : <h3 id="sec-1.1"><a name="target" id="target"></a><span  
> class="section-number-3">1.1</span> <span class="todo TODO"> TODO</ 
> span> heading </h3>
>
>  But I want:
> : <h3 id="target"><span class="section-number-3">1.1</span> <span  
> class="todo TODO"> TODO</span> heading </h3>

This would require you to assign custom targets to each and
every node.  This is why Org used generic section-number based IDs
as the basic id of the link, an provides any additional names
a anchors so that they can be targets as well. In particular, if
you give an entry an ID, this ID will also become an anchor
in the heading so that you can link to it.  I guess it does not
matter if the link points to the h3 element, or to an anchor
inside the heading right?

So you can use links with any names you like.

True, the table of contents does link to section numbers still.

I guess, with some work, we could reorganize the link storage
in a way that a user-given target of an ID become the preferred
hrefs and that section numbers will only be used when there is
not alternative.....

hmmmm.  How important is this.?

- Carsten


- Carsten


>
>
>
>  Since entries can already have IDs (I mean the property "ID",  
> obtained by C-c l for instance), this could now be easier to  
> implement.
>  As an extreme solution: If org-mode used exactly that ID to link to  
> the entry, I wouldn't mind changing the entry ID overall in my files  
> so that they have meaningful names instead of random data. Maybe I  
> wouldn't even mind having an HTML ID called b9c1a93e-2af4-4a41- 
> bfe3-8d2bd62c0614… (if it starts with a letter, it's still a valid  
> ID).
>
>
>  In case it's too complex to do this in org, do you know of some  
> script to replace the IDs after export?
>
>
>  Thanks,
>
> Daniel
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Custom entry IDs in HTML export

[Bernt Hansen]

Carsten Dominik <carsten.dominik@gmail.com> writes:

> I guess, with some work, we could reorganize the link storage
> in a way that a user-given target of an ID become the preferred
> hrefs and that section numbers will only be used when there is
> not alternative.....
>
> hmmmm.  How important is this.?

I think it would be good to do eventually but it's not hugely important
(to me).  I've been living with the current behaviour for a long time.

I post some of my task lists in HTML and paste a link to a task by
navigating to it from the TOC.  This allows other people to get directly
to the target task but it is fragile and only works for a short period
of time.

If I change the structure of the tasks above the linked-to item (archive
something to a different file, reorder tasks, etc) and export the
document again then the old link now goes to the wrong place.  It would
be better to use a link that survives document restructuring instead.
I've been too lazy to create manual links for my tasks -- I have tons of
tasks and I might link to 3 or 4 of them in 6 months so I haven't
bothered creating a manual link and re-exporting just for that.

This workflow would however would fix the issue I'm having with it - and
it's all supported right now -- except I have to write the link
manually.  If the link was used in the TOC instead of the standard link
then I would just

  - create the link
  - export
  - go there from the TOC and paste the URL wherever I need it

That would remove the error-prone step of creating the link manually
when passing it along to someone else.

Just my two cents.

-Bernt

Re: Re: Custom entry IDs in HTML export

[Sebastian Rose]

I don't think this is an important change.

Here some thoughts that come to mind in this context.



What we have now, just as Carstens said:

  # <<human-readable>>
  * Section B

Creates this headline in HTML:

  <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2 Section B </h2>

This is enough for all the use cases I can think of.

The section and headline may be detected through the anchor by any DOM
parser. Also, creating Org-files from Database entries or similar is
simple (Php):


fputs($fh, '
# <<id' . $row['id'] . '>>
* ' . $row['headline']);




If a change should be done, how will that change look like?



* Distinguishing automatic and human readable IDs

  One thing I like is, that we now _can_ distinguish the
  `human-readable-target' (human readable) from the `sec-2' (not human
  readable and not context related) using a regular expression.

  In org-info.js, I can now prefere the human readable ID in <a> from an
  automatic created one, and thus use that to create the links for `l'
  and `L'. The same holds true for other programming languages and
  parsers.

  If we open the <h3>'s ID for user defined values (bad), we can not
  distinguish those ID's using a regular expression and there is no way
  to detect the human readable one. There will be no way to _know_ that
  the <a>'s ID is the prefered one used for human readable links.

  If such a change should be done, I'd always prefer the (eventually
  existing) anchors ID for creating links.

  Conventions are not a bad thing in general, but they can lead to lot's
  of `if you...  else if... else...' in code and docs.


* Quality assurance

  The automatic IDs in the headline elements, and only those ID's,
  guaranty the functionality of export and cross referencing in an idiot
  proof way, which is what I prefer.




Regards,

  Sebastian



--
Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
Tel.:  +49 (0)511 - 36 58 472
Fax:   +49 (0)1805 - 233633 - 11044
mobil: +49 (0)173 - 83 93 417
Http:  www.emma-stil.de

Re: Re: Custom entry IDs in HTML export

[Daniel Clemente]

El dv, mar 27 2009, Sebastian Rose va escriure:
>
> What we have now, just as Carstens said:
>
>   # <<human-readable>>
>   * Section B
>
> Creates this headline in HTML:
>
>   <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2 Section B </h2>
>
> This is enough for all the use cases I can think of.
>

  Yes, this is enough except for two things:
1. The TOC still links to #sec-2 and the user can't change that
2. Your syntax doesn't fold very well in the outliner. I mean: if you use

>   # <<human-readable>>
>   * Section B

  then the comment appears at the end of the previous section, and you can miss it when you are viewing the heading „Section B“. I would swap both lines (solution 1):

>   * Section B
>   # <<human-readable>>

  But since there are already LOGBOOK drawers under the heading, it would be a lot clearer to use a property, like EXPORT_ID (solution 2):

> * Section B
>   :PROPERTIES:
>   :EXPORT_ID: human-readable
>   :END:


  In this way, the TOC can reliably find the EXPORT_ID, and then generate:
>   <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2 Section B </h2>

  (You could also leave *just* the human-readable id, but having two is not bad.


  I would prefer solution 1, but I don't because I'm not sure that the TOC can find the ID if it is written as a comment anywhere under the heading (and together with other things).

  Solution 2 involves thus: a new property to specify the human-readable entry ID, which will be used to link to the entry. The automatic ID (#sec-2) will still work for all entrys.


>
> * Distinguishing automatic and human readable IDs
>
>   One thing I like is, that we now _can_ distinguish the
>   `human-readable-target' (human readable) from the `sec-2' (not human
>   readable and not context related) using a regular expression.
>
>   In org-info.js, I can now prefere the human readable ID in <a> from an
>   automatic created one, and thus use that to create the links for `l'
>   and `L'. The same holds true for other programming languages and
>   parsers.
>
>   If we open the <h3>'s ID for user defined values (bad), we can not
>   distinguish those ID's using a regular expression and there is no way
>   to detect the human readable one. There will be no way to _know_ that
>   the <a>'s ID is the prefered one used for human readable links.
>

  Solution 2 doesn't break the parsing techniques you use; in fact it can also make clearer which ID is the human readable one and which one not.


  This is not extremely important; just useful:
- for pages with many incoming links from external sites
- to ensure link integrity (now you can't assure that links will still work in 1 year ... or in some weeks)
- to avoid that HTML visitors get directed to a wrong section and can't find what they searched


  Greetings,
Daniel

Re: Re: Custom entry IDs in HTML export

[Carsten Dominik]

Hi Sebastian,

I kind of like the idea to have a property that can be
used to set an ID, as an alternative to the <<target>>
notation.  Actually, using a property seems a lot cleaner,
thanks for coming up with this idea, Daniel.

I can also follow the reasoning that it is useful to have
the table of contents link to the human-readable id, because
it provides a general, simple workflow to retrieve a link that
will persist through changes of the document.  This workflow
was described also by Bernt earlier in this thread.

Finally, I also agree that the main id in the <h3> tag
should be the automatically generated one because this is
best for automatic processing and because of all the arguments
you have presented.

Would it cause problems for org-info.js if the toc points to
a user specified anchor in the headline, instead of the main
ID that is inside the <h3> tag?  THis would really be the only
required change.

- Carsten


On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:

> El dv, mar 27 2009, Sebastian Rose va escriure:
>>
>> What we have now, just as Carstens said:
>>
>>  # <<human-readable>>
>>  * Section B
>>
>> Creates this headline in HTML:
>>
>>  <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2  
>> Section B </h2>
>>
>> This is enough for all the use cases I can think of.
>>
>
>  Yes, this is enough except for two things:
> 1. The TOC still links to #sec-2 and the user can't change that
> 2. Your syntax doesn't fold very well in the outliner. I mean: if  
> you use
>
>>  # <<human-readable>>
>>  * Section B
>
>  then the comment appears at the end of the previous section, and  
> you can miss it when you are viewing the heading „Section B“. I  
> would swap both lines (solution 1):
>
>>  * Section B
>>  # <<human-readable>>
>
>  But since there are already LOGBOOK drawers under the heading, it  
> would be a lot clearer to use a property, like EXPORT_ID (solution 2):
>
>> * Section B
>>  :PROPERTIES:
>>  :EXPORT_ID: human-readable
>>  :END:
>
>
>  In this way, the TOC can reliably find the EXPORT_ID, and then  
> generate:
>>  <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2  
>> Section B </h2>
>
>  (You could also leave *just* the human-readable id, but having two  
> is not bad.
>
>
>  I would prefer solution 1, but I don't because I'm not sure that  
> the TOC can find the ID if it is written as a comment anywhere under  
> the heading (and together with other things).
>
>  Solution 2 involves thus: a new property to specify the human- 
> readable entry ID, which will be used to link to the entry. The  
> automatic ID (#sec-2) will still work for all entrys.
>
>
>>
>> * Distinguishing automatic and human readable IDs
>>
>>  One thing I like is, that we now _can_ distinguish the
>>  `human-readable-target' (human readable) from the `sec-2' (not human
>>  readable and not context related) using a regular expression.
>>
>>  In org-info.js, I can now prefere the human readable ID in <a>  
>> from an
>>  automatic created one, and thus use that to create the links for `l'
>>  and `L'. The same holds true for other programming languages and
>>  parsers.
>>
>>  If we open the <h3>'s ID for user defined values (bad), we can not
>>  distinguish those ID's using a regular expression and there is no  
>> way
>>  to detect the human readable one. There will be no way to _know_  
>> that
>>  the <a>'s ID is the prefered one used for human readable links.
>>
>
>  Solution 2 doesn't break the parsing techniques you use; in fact it  
> can also make clearer which ID is the human readable one and which  
> one not.
>
>
>  This is not extremely important; just useful:
> - for pages with many incoming links from external sites
> - to ensure link integrity (now you can't assure that links will  
> still work in 1 year ... or in some weeks)
> - to avoid that HTML visitors get directed to a wrong section and  
> can't find what they searched
>
>
>  Greetings,
> Daniel
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re: Custom entry IDs in HTML export

[Sebastian Rose]

Carsten Dominik <carsten.dominik@gmail.com> writes:
> Hi Sebastian,
>
> I kind of like the idea to have a property that can be
> used to set an ID, as an alternative to the <<target>>
> notation.  Actually, using a property seems a lot cleaner,
> thanks for coming up with this idea, Daniel.
>
> I can also follow the reasoning that it is useful to have
> the table of contents link to the human-readable id, because
> it provides a general, simple workflow to retrieve a link that
> will persist through changes of the document.  This workflow
> was described also by Bernt earlier in this thread.
>
> Finally, I also agree that the main id in the <h3> tag
> should be the automatically generated one because this is
> best for automatic processing and because of all the arguments
> you have presented.
>
> Would it cause problems for org-info.js if the toc points to
> a user specified anchor in the headline, instead of the main
> ID that is inside the <h3> tag?  THis would really be the only
> required change.


I'll have to test this before I can give a final answer to this
question.

But regardless of the results, I will adjust the script to reflect that
change. The script should not rule the HTML export and it will be an
easy thing to do.

  Sebastian



> - Carsten
>
>
> On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:
>
>> El dv, mar 27 2009, Sebastian Rose va escriure:
>>>
>>> What we have now, just as Carstens said:
>>>
>>>  # <<human-readable>>
>>>  * Section B
>>>
>>> Creates this headline in HTML:
>>>
>>>  <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2 Section B
>>> </h2>
>>>
>>> This is enough for all the use cases I can think of.
>>>
>>
>>  Yes, this is enough except for two things:
>> 1. The TOC still links to #sec-2 and the user can't change that
>> 2. Your syntax doesn't fold very well in the outliner. I mean: if you use
>>
>>>  # <<human-readable>>
>>>  * Section B
>>
>>  then the comment appears at the end of the previous section, and you can miss
>> it when you are viewing the heading „Section B“. I  would swap both lines
>> (solution 1):
>>
>>>  * Section B
>>>  # <<human-readable>>
>>
>>  But since there are already LOGBOOK drawers under the heading, it would be a
>> lot clearer to use a property, like EXPORT_ID (solution 2):
>>
>>> * Section B
>>>  :PROPERTIES:
>>>  :EXPORT_ID: human-readable
>>>  :END:
>>
>>
>>  In this way, the TOC can reliably find the EXPORT_ID, and then generate:
>>>  <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2 Section B
>>> </h2>
>>
>>  (You could also leave *just* the human-readable id, but having two is not
>> bad.
>>
>>
>>  I would prefer solution 1, but I don't because I'm not sure that the TOC can
>> find the ID if it is written as a comment anywhere under  the heading (and
>> together with other things).
>>
>>  Solution 2 involves thus: a new property to specify the human-
>> readable entry ID, which will be used to link to the entry. The automatic ID
>> (#sec-2) will still work for all entrys.
>>
>>
>>>
>>> * Distinguishing automatic and human readable IDs
>>>
>>>  One thing I like is, that we now _can_ distinguish the
>>>  `human-readable-target' (human readable) from the `sec-2' (not human
>>>  readable and not context related) using a regular expression.
>>>
>>>  In org-info.js, I can now prefere the human readable ID in <a> from an
>>>  automatic created one, and thus use that to create the links for `l'
>>>  and `L'. The same holds true for other programming languages and
>>>  parsers.
>>>
>>>  If we open the <h3>'s ID for user defined values (bad), we can not
>>>  distinguish those ID's using a regular expression and there is no way
>>>  to detect the human readable one. There will be no way to _know_ that
>>>  the <a>'s ID is the prefered one used for human readable links.
>>>
>>
>>  Solution 2 doesn't break the parsing techniques you use; in fact it can also
>> make clearer which ID is the human readable one and which  one not.
>>
>>
>>  This is not extremely important; just useful:
>> - for pages with many incoming links from external sites
>> - to ensure link integrity (now you can't assure that links will still work in
>> 1 year ... or in some weeks)
>> - to avoid that HTML visitors get directed to a wrong section and can't find
>> what they searched
>>
>>
>>  Greetings,
>> Daniel
>>
>>
>> _______________________________________________
>> Emacs-orgmode mailing list
>> Remember: use `Reply All' to send replies to the list.
>> Emacs-orgmode@gnu.org
>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>

-- 
Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
Tel.:  +49 (0)511 - 36 58 472
Fax:   +49 (0)1805 - 233633 - 11044
mobil: +49 (0)173 - 83 93 417
Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
Http:  www.emma-stil.de

Re: Re: Custom entry IDs in HTML export

[Carsten Dominik]

On Apr 16, 2009, at 10:50 AM, Sebastian Rose wrote:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>> Hi Sebastian,
>>
>> I kind of like the idea to have a property that can be
>> used to set an ID, as an alternative to the <<target>>
>> notation.  Actually, using a property seems a lot cleaner,
>> thanks for coming up with this idea, Daniel.
>>
>> I can also follow the reasoning that it is useful to have
>> the table of contents link to the human-readable id, because
>> it provides a general, simple workflow to retrieve a link that
>> will persist through changes of the document.  This workflow
>> was described also by Bernt earlier in this thread.
>>
>> Finally, I also agree that the main id in the <h3> tag
>> should be the automatically generated one because this is
>> best for automatic processing and because of all the arguments
>> you have presented.
>>
>> Would it cause problems for org-info.js if the toc points to
>> a user specified anchor in the headline, instead of the main
>> ID that is inside the <h3> tag?  THis would really be the only
>> required change.
>
>
> I'll have to test this before I can give a final answer to this
> question.
>
> But regardless of the results, I will adjust the script to reflect  
> that
> change. The script should not rule the HTML export and it will be an
> easy thing to do.

But I do want to hear any counter arguments you might have....

- Carsten

>
>  Sebastian
>
>
>
>> - Carsten
>>
>>
>> On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:
>>
>>> El dv, mar 27 2009, Sebastian Rose va escriure:
>>>>
>>>> What we have now, just as Carstens said:
>>>>
>>>> # <<human-readable>>
>>>> * Section B
>>>>
>>>> Creates this headline in HTML:
>>>>
>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2  
>>>> Section B
>>>> </h2>
>>>>
>>>> This is enough for all the use cases I can think of.
>>>>
>>>
>>> Yes, this is enough except for two things:
>>> 1. The TOC still links to #sec-2 and the user can't change that
>>> 2. Your syntax doesn't fold very well in the outliner. I mean: if  
>>> you use
>>>
>>>> # <<human-readable>>
>>>> * Section B
>>>
>>> then the comment appears at the end of the previous section, and  
>>> you can miss
>>> it when you are viewing the heading „Section B“. I  would swap  
>>> both lines
>>> (solution 1):
>>>
>>>> * Section B
>>>> # <<human-readable>>
>>>
>>> But since there are already LOGBOOK drawers under the heading, it  
>>> would be a
>>> lot clearer to use a property, like EXPORT_ID (solution 2):
>>>
>>>> * Section B
>>>> :PROPERTIES:
>>>> :EXPORT_ID: human-readable
>>>> :END:
>>>
>>>
>>> In this way, the TOC can reliably find the EXPORT_ID, and then  
>>> generate:
>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2  
>>>> Section B
>>>> </h2>
>>>
>>> (You could also leave *just* the human-readable id, but having two  
>>> is not
>>> bad.
>>>
>>>
>>> I would prefer solution 1, but I don't because I'm not sure that  
>>> the TOC can
>>> find the ID if it is written as a comment anywhere under  the  
>>> heading (and
>>> together with other things).
>>>
>>> Solution 2 involves thus: a new property to specify the human-
>>> readable entry ID, which will be used to link to the entry. The  
>>> automatic ID
>>> (#sec-2) will still work for all entrys.
>>>
>>>
>>>>
>>>> * Distinguishing automatic and human readable IDs
>>>>
>>>> One thing I like is, that we now _can_ distinguish the
>>>> `human-readable-target' (human readable) from the `sec-2' (not  
>>>> human
>>>> readable and not context related) using a regular expression.
>>>>
>>>> In org-info.js, I can now prefere the human readable ID in <a>  
>>>> from an
>>>> automatic created one, and thus use that to create the links for  
>>>> `l'
>>>> and `L'. The same holds true for other programming languages and
>>>> parsers.
>>>>
>>>> If we open the <h3>'s ID for user defined values (bad), we can not
>>>> distinguish those ID's using a regular expression and there is no  
>>>> way
>>>> to detect the human readable one. There will be no way to _know_  
>>>> that
>>>> the <a>'s ID is the prefered one used for human readable links.
>>>>
>>>
>>> Solution 2 doesn't break the parsing techniques you use; in fact  
>>> it can also
>>> make clearer which ID is the human readable one and which  one not.
>>>
>>>
>>> This is not extremely important; just useful:
>>> - for pages with many incoming links from external sites
>>> - to ensure link integrity (now you can't assure that links will  
>>> still work in
>>> 1 year ... or in some weeks)
>>> - to avoid that HTML visitors get directed to a wrong section and  
>>> can't find
>>> what they searched
>>>
>>>
>>> Greetings,
>>> Daniel
>>>
>>>
>>> _______________________________________________
>>> Emacs-orgmode mailing list
>>> Remember: use `Reply All' to send replies to the list.
>>> Emacs-orgmode@gnu.org
>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>
>
> -- 
> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
> Hannover
> Tel.:  +49 (0)511 - 36 58 472
> Fax:   +49 (0)1805 - 233633 - 11044
> mobil: +49 (0)173 - 83 93 417
> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
> Http:  www.emma-stil.de

Re: Re: Custom entry IDs in HTML export

[Sebastian Rose]

Hm - counter arguments?

The only counter argument is, that hand made IDs for links are prone to
error. But that risk should be up to the user.

I actually changed my mind a little in this concern.

If the user clicks a section link in the toc to jump to a section, he
can bookmark the page with exactly that jump target. If the jump target
(the ID) is human readable, the bookmark is more verbose.


Just one wish:

  The containers should reflect that change (HRID = human readable id):

  <div   id="outline-container-HRID">
    <h4  id="HRID">                   headline    </h4>
    <div id="outline-text-HRID">
       sections content...
    </div>
  </div>


That way the script would keep working with older pages.
Automatic IDs and human readable ones could be mixed.


The '<a id="">' anchors are scanned anyway, as are all jump targets in
the page.




Maybe this is even the point to re-work the parser of org-info.js to
become independent of the TOC at all. The script could search for
headings instead. That's more work, but the script would then work for
all HTML pages with a structure similar to the org-export's one:


 <div id=""><hx id=""></hx><div>content</div></div> 

but I could postpone this, if you fullfill my wish above.



Best wishes

   Sebastian




Carsten Dominik <carsten.dominik@gmail.com> writes:
> On Apr 16, 2009, at 10:50 AM, Sebastian Rose wrote:
>
>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>> Hi Sebastian,
>>>
>>> I kind of like the idea to have a property that can be
>>> used to set an ID, as an alternative to the <<target>>
>>> notation.  Actually, using a property seems a lot cleaner,
>>> thanks for coming up with this idea, Daniel.
>>>
>>> I can also follow the reasoning that it is useful to have
>>> the table of contents link to the human-readable id, because
>>> it provides a general, simple workflow to retrieve a link that
>>> will persist through changes of the document.  This workflow
>>> was described also by Bernt earlier in this thread.
>>>
>>> Finally, I also agree that the main id in the <h3> tag
>>> should be the automatically generated one because this is
>>> best for automatic processing and because of all the arguments
>>> you have presented.
>>>
>>> Would it cause problems for org-info.js if the toc points to
>>> a user specified anchor in the headline, instead of the main
>>> ID that is inside the <h3> tag?  THis would really be the only
>>> required change.
>>
>>
>> I'll have to test this before I can give a final answer to this
>> question.
>>
>> But regardless of the results, I will adjust the script to reflect that
>> change. The script should not rule the HTML export and it will be an
>> easy thing to do.
>
> But I do want to hear any counter arguments you might have....
>
> - Carsten
>
>>
>>  Sebastian
>>
>>
>>
>>> - Carsten
>>>
>>>
>>> On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:
>>>
>>>> El dv, mar 27 2009, Sebastian Rose va escriure:
>>>>>
>>>>> What we have now, just as Carstens said:
>>>>>
>>>>> # <<human-readable>>
>>>>> * Section B
>>>>>
>>>>> Creates this headline in HTML:
>>>>>
>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2 Section B
>>>>> </h2>
>>>>>
>>>>> This is enough for all the use cases I can think of.
>>>>>
>>>>
>>>> Yes, this is enough except for two things:
>>>> 1. The TOC still links to #sec-2 and the user can't change that
>>>> 2. Your syntax doesn't fold very well in the outliner. I mean: if you use
>>>>
>>>>> # <<human-readable>>
>>>>> * Section B
>>>>
>>>> then the comment appears at the end of the previous section, and you can
>>>> miss
>>>> it when you are viewing the heading „Section B“. I  would swap both lines
>>>> (solution 1):
>>>>
>>>>> * Section B
>>>>> # <<human-readable>>
>>>>
>>>> But since there are already LOGBOOK drawers under the heading, it would be a
>>>> lot clearer to use a property, like EXPORT_ID (solution 2):
>>>>
>>>>> * Section B
>>>>> :PROPERTIES:
>>>>> :EXPORT_ID: human-readable
>>>>> :END:
>>>>
>>>>
>>>> In this way, the TOC can reliably find the EXPORT_ID, and then generate:
>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></a>2 Section B
>>>>> </h2>
>>>>
>>>> (You could also leave *just* the human-readable id, but having two is not
>>>> bad.
>>>>
>>>>
>>>> I would prefer solution 1, but I don't because I'm not sure that the TOC can
>>>> find the ID if it is written as a comment anywhere under  the heading (and
>>>> together with other things).
>>>>
>>>> Solution 2 involves thus: a new property to specify the human-
>>>> readable entry ID, which will be used to link to the entry. The automatic ID
>>>> (#sec-2) will still work for all entrys.
>>>>
>>>>
>>>>>
>>>>> * Distinguishing automatic and human readable IDs
>>>>>
>>>>> One thing I like is, that we now _can_ distinguish the
>>>>> `human-readable-target' (human readable) from the `sec-2' (not human
>>>>> readable and not context related) using a regular expression.
>>>>>
>>>>> In org-info.js, I can now prefere the human readable ID in <a> from an
>>>>> automatic created one, and thus use that to create the links for `l'
>>>>> and `L'. The same holds true for other programming languages and
>>>>> parsers.
>>>>>
>>>>> If we open the <h3>'s ID for user defined values (bad), we can not
>>>>> distinguish those ID's using a regular expression and there is no way
>>>>> to detect the human readable one. There will be no way to _know_ that
>>>>> the <a>'s ID is the prefered one used for human readable links.
>>>>>
>>>>
>>>> Solution 2 doesn't break the parsing techniques you use; in fact it can also
>>>> make clearer which ID is the human readable one and which  one not.
>>>>
>>>>
>>>> This is not extremely important; just useful:
>>>> - for pages with many incoming links from external sites
>>>> - to ensure link integrity (now you can't assure that links will still work
>>>> in
>>>> 1 year ... or in some weeks)
>>>> - to avoid that HTML visitors get directed to a wrong section and can't find
>>>> what they searched
>>>>
>>>>
>>>> Greetings,
>>>> Daniel
>>>>
>>>>
>>>> _______________________________________________
>>>> Emacs-orgmode mailing list
>>>> Remember: use `Reply All' to send replies to the list.
>>>> Emacs-orgmode@gnu.org
>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>
>>
>> --
>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
>> Tel.:  +49 (0)511 - 36 58 472
>> Fax:   +49 (0)1805 - 233633 - 11044
>> mobil: +49 (0)173 - 83 93 417
>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>> Http:  www.emma-stil.de
>

-- 
Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
Tel.:  +49 (0)511 - 36 58 472
Fax:   +49 (0)1805 - 233633 - 11044
mobil: +49 (0)173 - 83 93 417
Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
Http:  www.emma-stil.de

Re: Re: Custom entry IDs in HTML export

[Carsten Dominik]

Hi Sebastian,

On Apr 16, 2009, at 3:14 PM, Sebastian Rose wrote:

> Hm - counter arguments?
>
> The only counter argument is, that hand made IDs for links are prone  
> to
> error. But that risk should be up to the user.

Yes.  and during the export, I can actually check and throw a warning  
or an error if the same custom ID shows up twice.

>
> I actually changed my mind a little in this concern.
>
> If the user clicks a section link in the toc to jump to a section, he
> can bookmark the page with exactly that jump target. If the jump  
> target
> (the ID) is human readable, the bookmark is more verbose.

Yes, this is really the best application.  Also, when hovering over  
internal links, it is helpful if the link displays the human-readable  
form.

> Just one wish:
>
> The containers should reflect that change (HRID = human readable id):
>
> <div   id="outline-container-HRID">
> <h4  id="HRID">                   headline    </h4>
> <div id="outline-text-HRID">
>    sections content...
> </div>
> </div>


Sure, we can do this.  I would then add sec-xxx as one
of the alternative anchors as well.

However:  If I make the structure as you indicate above,
do I understand correctly that the structure of a section without a  
human-readable id should be changed to this:

<div   id="outline-container-sec-1.1">
<h4  id="sec-1.1">                   headline    </h4>
<div id="outline-text-sec-1.1">
    sections content...
</div>
</div>


Note the "sec-" which is added to the stuff that currently
defines the structure.


> That way the script would keep working with older pages.
> Automatic IDs and human readable ones could be mixed.
>
>
> The '<a id="">' anchors are scanned anyway, as are all jump targets in
> the page.

Yes, you implemented that some time ago, I remember.

>
> Maybe this is even the point to re-work the parser of org-info.js to
> become independent of the TOC at all. The script could search for
> headings instead. That's more work, but the script would then work for
> all HTML pages with a structure similar to the org-export's one:

So this would mean, we could read web pages with your java
support even if those webpages were not created with Org?
Pretty cool.

> <div id=""><hx id=""></hx><div>content</div></div>
>
> but I could postpone this, if you fullfill my wish above.


Best wishes

- Carsten

>
>
> Best wishes
>
> Sebastian
>
>
>
>
> Carsten Dominik <carsten.dominik@gmail.com> writes:
>> On Apr 16, 2009, at 10:50 AM, Sebastian Rose wrote:
>>
>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>> Hi Sebastian,
>>>>
>>>> I kind of like the idea to have a property that can be
>>>> used to set an ID, as an alternative to the <<target>>
>>>> notation.  Actually, using a property seems a lot cleaner,
>>>> thanks for coming up with this idea, Daniel.
>>>>
>>>> I can also follow the reasoning that it is useful to have
>>>> the table of contents link to the human-readable id, because
>>>> it provides a general, simple workflow to retrieve a link that
>>>> will persist through changes of the document.  This workflow
>>>> was described also by Bernt earlier in this thread.
>>>>
>>>> Finally, I also agree that the main id in the <h3> tag
>>>> should be the automatically generated one because this is
>>>> best for automatic processing and because of all the arguments
>>>> you have presented.
>>>>
>>>> Would it cause problems for org-info.js if the toc points to
>>>> a user specified anchor in the headline, instead of the main
>>>> ID that is inside the <h3> tag?  THis would really be the only
>>>> required change.
>>>
>>>
>>> I'll have to test this before I can give a final answer to this
>>> question.
>>>
>>> But regardless of the results, I will adjust the script to reflect  
>>> that
>>> change. The script should not rule the HTML export and it will be an
>>> easy thing to do.
>>
>> But I do want to hear any counter arguments you might have....
>>
>> - Carsten
>>
>>>
>>> Sebastian
>>>
>>>
>>>
>>>> - Carsten
>>>>
>>>>
>>>> On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:
>>>>
>>>>> El dv, mar 27 2009, Sebastian Rose va escriure:
>>>>>>
>>>>>> What we have now, just as Carstens said:
>>>>>>
>>>>>> # <<human-readable>>
>>>>>> * Section B
>>>>>>
>>>>>> Creates this headline in HTML:
>>>>>>
>>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></ 
>>>>>> a>2 Section B
>>>>>> </h2>
>>>>>>
>>>>>> This is enough for all the use cases I can think of.
>>>>>>
>>>>>
>>>>> Yes, this is enough except for two things:
>>>>> 1. The TOC still links to #sec-2 and the user can't change that
>>>>> 2. Your syntax doesn't fold very well in the outliner. I mean:  
>>>>> if you use
>>>>>
>>>>>> # <<human-readable>>
>>>>>> * Section B
>>>>>
>>>>> then the comment appears at the end of the previous section, and  
>>>>> you can
>>>>> miss
>>>>> it when you are viewing the heading „Section B“. I  would swap  
>>>>> both lines
>>>>> (solution 1):
>>>>>
>>>>>> * Section B
>>>>>> # <<human-readable>>
>>>>>
>>>>> But since there are already LOGBOOK drawers under the heading,  
>>>>> it would be a
>>>>> lot clearer to use a property, like EXPORT_ID (solution 2):
>>>>>
>>>>>> * Section B
>>>>>> :PROPERTIES:
>>>>>> :EXPORT_ID: human-readable
>>>>>> :END:
>>>>>
>>>>>
>>>>> In this way, the TOC can reliably find the EXPORT_ID, and then  
>>>>> generate:
>>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></ 
>>>>>> a>2 Section B
>>>>>> </h2>
>>>>>
>>>>> (You could also leave *just* the human-readable id, but having  
>>>>> two is not
>>>>> bad.
>>>>>
>>>>>
>>>>> I would prefer solution 1, but I don't because I'm not sure that  
>>>>> the TOC can
>>>>> find the ID if it is written as a comment anywhere under  the  
>>>>> heading (and
>>>>> together with other things).
>>>>>
>>>>> Solution 2 involves thus: a new property to specify the human-
>>>>> readable entry ID, which will be used to link to the entry. The  
>>>>> automatic ID
>>>>> (#sec-2) will still work for all entrys.
>>>>>
>>>>>
>>>>>>
>>>>>> * Distinguishing automatic and human readable IDs
>>>>>>
>>>>>> One thing I like is, that we now _can_ distinguish the
>>>>>> `human-readable-target' (human readable) from the `sec-2' (not  
>>>>>> human
>>>>>> readable and not context related) using a regular expression.
>>>>>>
>>>>>> In org-info.js, I can now prefere the human readable ID in <a>  
>>>>>> from an
>>>>>> automatic created one, and thus use that to create the links  
>>>>>> for `l'
>>>>>> and `L'. The same holds true for other programming languages and
>>>>>> parsers.
>>>>>>
>>>>>> If we open the <h3>'s ID for user defined values (bad), we can  
>>>>>> not
>>>>>> distinguish those ID's using a regular expression and there is  
>>>>>> no way
>>>>>> to detect the human readable one. There will be no way to  
>>>>>> _know_ that
>>>>>> the <a>'s ID is the prefered one used for human readable links.
>>>>>>
>>>>>
>>>>> Solution 2 doesn't break the parsing techniques you use; in fact  
>>>>> it can also
>>>>> make clearer which ID is the human readable one and which  one  
>>>>> not.
>>>>>
>>>>>
>>>>> This is not extremely important; just useful:
>>>>> - for pages with many incoming links from external sites
>>>>> - to ensure link integrity (now you can't assure that links will  
>>>>> still work
>>>>> in
>>>>> 1 year ... or in some weeks)
>>>>> - to avoid that HTML visitors get directed to a wrong section  
>>>>> and can't find
>>>>> what they searched
>>>>>
>>>>>
>>>>> Greetings,
>>>>> Daniel
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Emacs-orgmode mailing list
>>>>> Remember: use `Reply All' to send replies to the list.
>>>>> Emacs-orgmode@gnu.org
>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>
>>>
>>> --
>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
>>> Hannover
>>> Tel.:  +49 (0)511 - 36 58 472
>>> Fax:   +49 (0)1805 - 233633 - 11044
>>> mobil: +49 (0)173 - 83 93 417
>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>> Http:  www.emma-stil.de
>>
>
> -- 
> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
> Hannover
> Tel.:  +49 (0)511 - 36 58 472
> Fax:   +49 (0)1805 - 233633 - 11044
> mobil: +49 (0)173 - 83 93 417
> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
> Http:  www.emma-stil.de

Re: Re: Custom entry IDs in HTML export

[Sebastian Rose]

Carsten Dominik <carsten.dominik@gmail.com> writes:
> Hi Sebastian,
>
> On Apr 16, 2009, at 3:14 PM, Sebastian Rose wrote:
>
>> Hm - counter arguments?
>>
>> The only counter argument is, that hand made IDs for links are prone to
>> error. But that risk should be up to the user.
>
> Yes.  and during the export, I can actually check and throw a warning or an
> error if the same custom ID shows up twice.
>
>>
>> I actually changed my mind a little in this concern.
>>
>> If the user clicks a section link in the toc to jump to a section, he
>> can bookmark the page with exactly that jump target. If the jump target
>> (the ID) is human readable, the bookmark is more verbose.
>
> Yes, this is really the best application.  Also, when hovering over internal
> links, it is helpful if the link displays the human-readable  form.
>
>> Just one wish:
>>
>> The containers should reflect that change (HRID = human readable id):
>>
>> <div   id="outline-container-HRID">
>> <h4  id="HRID">                   headline    </h4>
>> <div id="outline-text-HRID">
>>    sections content...
>> </div>
>> </div>
>
>
> Sure, we can do this.  I would then add sec-xxx as one
> of the alternative anchors as well.
>
> However:  If I make the structure as you indicate above,
> do I understand correctly that the structure of a section without a
> human-readable id should be changed to this:
>
> <div   id="outline-container-sec-1.1">
> <h4  id="sec-1.1">                   headline    </h4>
> <div id="outline-text-sec-1.1">
>    sections content...
> </div>
> </div>
>
>
> Note the "sec-" which is added to the stuff that currently
> defines the structure.



I considered the `sec-' part of the automatic IDs.

In either case I'd have to adjust org-info.js. So why not go for the
human readable IDs without `sec-'?


Right now we have:

<div id="outline-container-2" class="outline-2">
<h2 id="sec-2"><span class="section-number-2">2</span> Things I want to find out </h2>
<div class="outline-text-2" id="text-2">

The `sec-' part is in the headlines ID only.



   Sebastian




>> That way the script would keep working with older pages.
>> Automatic IDs and human readable ones could be mixed.
>>
>>
>> The '<a id="">' anchors are scanned anyway, as are all jump targets in
>> the page.
>
> Yes, you implemented that some time ago, I remember.
>
>>
>> Maybe this is even the point to re-work the parser of org-info.js to
>> become independent of the TOC at all. The script could search for
>> headings instead. That's more work, but the script would then work for
>> all HTML pages with a structure similar to the org-export's one:
>
> So this would mean, we could read web pages with your java
> support even if those webpages were not created with Org?
> Pretty cool.
>
>> <div id=""><hx id=""></hx><div>content</div></div>
>>
>> but I could postpone this, if you fullfill my wish above.
>
>
> Best wishes
>
> - Carsten
>
>>
>>
>> Best wishes
>>
>> Sebastian
>>
>>
>>
>>
>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>> On Apr 16, 2009, at 10:50 AM, Sebastian Rose wrote:
>>>
>>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>>> Hi Sebastian,
>>>>>
>>>>> I kind of like the idea to have a property that can be
>>>>> used to set an ID, as an alternative to the <<target>>
>>>>> notation.  Actually, using a property seems a lot cleaner,
>>>>> thanks for coming up with this idea, Daniel.
>>>>>
>>>>> I can also follow the reasoning that it is useful to have
>>>>> the table of contents link to the human-readable id, because
>>>>> it provides a general, simple workflow to retrieve a link that
>>>>> will persist through changes of the document.  This workflow
>>>>> was described also by Bernt earlier in this thread.
>>>>>
>>>>> Finally, I also agree that the main id in the <h3> tag
>>>>> should be the automatically generated one because this is
>>>>> best for automatic processing and because of all the arguments
>>>>> you have presented.
>>>>>
>>>>> Would it cause problems for org-info.js if the toc points to
>>>>> a user specified anchor in the headline, instead of the main
>>>>> ID that is inside the <h3> tag?  THis would really be the only
>>>>> required change.
>>>>
>>>>
>>>> I'll have to test this before I can give a final answer to this
>>>> question.
>>>>
>>>> But regardless of the results, I will adjust the script to reflect that
>>>> change. The script should not rule the HTML export and it will be an
>>>> easy thing to do.
>>>
>>> But I do want to hear any counter arguments you might have....
>>>
>>> - Carsten
>>>
>>>>
>>>> Sebastian
>>>>
>>>>
>>>>
>>>>> - Carsten
>>>>>
>>>>>
>>>>> On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:
>>>>>
>>>>>> El dv, mar 27 2009, Sebastian Rose va escriure:
>>>>>>>
>>>>>>> What we have now, just as Carstens said:
>>>>>>>
>>>>>>> # <<human-readable>>
>>>>>>> * Section B
>>>>>>>
>>>>>>> Creates this headline in HTML:
>>>>>>>
>>>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></
>>>>>>> a>2 Section B
>>>>>>> </h2>
>>>>>>>
>>>>>>> This is enough for all the use cases I can think of.
>>>>>>>
>>>>>>
>>>>>> Yes, this is enough except for two things:
>>>>>> 1. The TOC still links to #sec-2 and the user can't change that
>>>>>> 2. Your syntax doesn't fold very well in the outliner. I mean: if you use
>>>>>>
>>>>>>> # <<human-readable>>
>>>>>>> * Section B
>>>>>>
>>>>>> then the comment appears at the end of the previous section, and you can
>>>>>> miss
>>>>>> it when you are viewing the heading „Section B“. I  would swap both lines
>>>>>> (solution 1):
>>>>>>
>>>>>>> * Section B
>>>>>>> # <<human-readable>>
>>>>>>
>>>>>> But since there are already LOGBOOK drawers under the heading, it would be
>>>>>> a
>>>>>> lot clearer to use a property, like EXPORT_ID (solution 2):
>>>>>>
>>>>>>> * Section B
>>>>>>> :PROPERTIES:
>>>>>>> :EXPORT_ID: human-readable
>>>>>>> :END:
>>>>>>
>>>>>>
>>>>>> In this way, the TOC can reliably find the EXPORT_ID, and then generate:
>>>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></
>>>>>>> a>2 Section B
>>>>>>> </h2>
>>>>>>
>>>>>> (You could also leave *just* the human-readable id, but having two is not
>>>>>> bad.
>>>>>>
>>>>>>
>>>>>> I would prefer solution 1, but I don't because I'm not sure that the TOC
>>>>>> can
>>>>>> find the ID if it is written as a comment anywhere under  the heading (and
>>>>>> together with other things).
>>>>>>
>>>>>> Solution 2 involves thus: a new property to specify the human-
>>>>>> readable entry ID, which will be used to link to the entry. The automatic
>>>>>> ID
>>>>>> (#sec-2) will still work for all entrys.
>>>>>>
>>>>>>
>>>>>>>
>>>>>>> * Distinguishing automatic and human readable IDs
>>>>>>>
>>>>>>> One thing I like is, that we now _can_ distinguish the
>>>>>>> `human-readable-target' (human readable) from the `sec-2' (not human
>>>>>>> readable and not context related) using a regular expression.
>>>>>>>
>>>>>>> In org-info.js, I can now prefere the human readable ID in <a> from an
>>>>>>> automatic created one, and thus use that to create the links for `l'
>>>>>>> and `L'. The same holds true for other programming languages and
>>>>>>> parsers.
>>>>>>>
>>>>>>> If we open the <h3>'s ID for user defined values (bad), we can not
>>>>>>> distinguish those ID's using a regular expression and there is no way
>>>>>>> to detect the human readable one. There will be no way to _know_ that
>>>>>>> the <a>'s ID is the prefered one used for human readable links.
>>>>>>>
>>>>>>
>>>>>> Solution 2 doesn't break the parsing techniques you use; in fact it can
>>>>>> also
>>>>>> make clearer which ID is the human readable one and which  one not.
>>>>>>
>>>>>>
>>>>>> This is not extremely important; just useful:
>>>>>> - for pages with many incoming links from external sites
>>>>>> - to ensure link integrity (now you can't assure that links will still
>>>>>> work
>>>>>> in
>>>>>> 1 year ... or in some weeks)
>>>>>> - to avoid that HTML visitors get directed to a wrong section and can't
>>>>>> find
>>>>>> what they searched
>>>>>>
>>>>>>
>>>>>> Greetings,
>>>>>> Daniel
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> Emacs-orgmode mailing list
>>>>>> Remember: use `Reply All' to send replies to the list.
>>>>>> Emacs-orgmode@gnu.org
>>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>>
>>>>
>>>> --
>>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
>>>> Tel.:  +49 (0)511 - 36 58 472
>>>> Fax:   +49 (0)1805 - 233633 - 11044
>>>> mobil: +49 (0)173 - 83 93 417
>>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>>> Http:  www.emma-stil.de
>>>
>>
>> --
>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
>> Tel.:  +49 (0)511 - 36 58 472
>> Fax:   +49 (0)1805 - 233633 - 11044
>> mobil: +49 (0)173 - 83 93 417
>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>> Http:  www.emma-stil.de
>

-- 
Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
Tel.:  +49 (0)511 - 36 58 472
Fax:   +49 (0)1805 - 233633 - 11044
mobil: +49 (0)173 - 83 93 417
Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
Http:  www.emma-stil.de

Re: Re: Custom entry IDs in HTML export

[Carsten Dominik]

On Apr 16, 2009, at 10:50 PM, Sebastian Rose wrote:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>> Hi Sebastian,
>>
>> On Apr 16, 2009, at 3:14 PM, Sebastian Rose wrote:
>>
>>> Hm - counter arguments?
>>>
>>> The only counter argument is, that hand made IDs for links are  
>>> prone to
>>> error. But that risk should be up to the user.
>>
>> Yes.  and during the export, I can actually check and throw a  
>> warning or an
>> error if the same custom ID shows up twice.
>>
>>>
>>> I actually changed my mind a little in this concern.
>>>
>>> If the user clicks a section link in the toc to jump to a section,  
>>> he
>>> can bookmark the page with exactly that jump target. If the jump  
>>> target
>>> (the ID) is human readable, the bookmark is more verbose.
>>
>> Yes, this is really the best application.  Also, when hovering over  
>> internal
>> links, it is helpful if the link displays the human-readable  form.
>>
>>> Just one wish:
>>>
>>> The containers should reflect that change (HRID = human readable  
>>> id):
>>>
>>> <div   id="outline-container-HRID">
>>> <h4  id="HRID">                   headline    </h4>
>>> <div id="outline-text-HRID">
>>>   sections content...
>>> </div>
>>> </div>
>>
>>
>> Sure, we can do this.  I would then add sec-xxx as one
>> of the alternative anchors as well.
>>
>> However:  If I make the structure as you indicate above,
>> do I understand correctly that the structure of a section without a
>> human-readable id should be changed to this:
>>
>> <div   id="outline-container-sec-1.1">
>> <h4  id="sec-1.1">                   headline    </h4>
>> <div id="outline-text-sec-1.1">
>>   sections content...
>> </div>
>> </div>
>>
>>
>> Note the "sec-" which is added to the stuff that currently
>> defines the structure.
>
>
>
> I considered the `sec-' part of the automatic IDs.
>
> In either case I'd have to adjust org-info.js. So why not go for the
> human readable IDs without `sec-'?
>
>
> Right now we have:
>
> <div id="outline-container-2" class="outline-2">
> <h2 id="sec-2"><span class="section-number-2">2</span> Things I want  
> to find out </h2>
> <div class="outline-text-2" id="text-2">
>
> The `sec-' part is in the headlines ID only.


Why?  Because this introduced a parsing inconsistency for you between  
automatic and custom IDs.  Because for the automatic ones, you need to  
strip "sec-" to retrieve the correct suffix for the container etc  
names.  With the custom IDs, no such stripping should be done.  Does  
this not make things harder?

- Carsten

>
>
>
>   Sebastian
>
>
>
>
>>> That way the script would keep working with older pages.
>>> Automatic IDs and human readable ones could be mixed.
>>>
>>>
>>> The '<a id="">' anchors are scanned anyway, as are all jump  
>>> targets in
>>> the page.
>>
>> Yes, you implemented that some time ago, I remember.
>>
>>>
>>> Maybe this is even the point to re-work the parser of org-info.js to
>>> become independent of the TOC at all. The script could search for
>>> headings instead. That's more work, but the script would then work  
>>> for
>>> all HTML pages with a structure similar to the org-export's one:
>>
>> So this would mean, we could read web pages with your java
>> support even if those webpages were not created with Org?
>> Pretty cool.
>>
>>> <div id=""><hx id=""></hx><div>content</div></div>
>>>
>>> but I could postpone this, if you fullfill my wish above.
>>
>>
>> Best wishes
>>
>> - Carsten
>>
>>>
>>>
>>> Best wishes
>>>
>>> Sebastian
>>>
>>>
>>>
>>>
>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>> On Apr 16, 2009, at 10:50 AM, Sebastian Rose wrote:
>>>>
>>>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>>>> Hi Sebastian,
>>>>>>
>>>>>> I kind of like the idea to have a property that can be
>>>>>> used to set an ID, as an alternative to the <<target>>
>>>>>> notation.  Actually, using a property seems a lot cleaner,
>>>>>> thanks for coming up with this idea, Daniel.
>>>>>>
>>>>>> I can also follow the reasoning that it is useful to have
>>>>>> the table of contents link to the human-readable id, because
>>>>>> it provides a general, simple workflow to retrieve a link that
>>>>>> will persist through changes of the document.  This workflow
>>>>>> was described also by Bernt earlier in this thread.
>>>>>>
>>>>>> Finally, I also agree that the main id in the <h3> tag
>>>>>> should be the automatically generated one because this is
>>>>>> best for automatic processing and because of all the arguments
>>>>>> you have presented.
>>>>>>
>>>>>> Would it cause problems for org-info.js if the toc points to
>>>>>> a user specified anchor in the headline, instead of the main
>>>>>> ID that is inside the <h3> tag?  THis would really be the only
>>>>>> required change.
>>>>>
>>>>>
>>>>> I'll have to test this before I can give a final answer to this
>>>>> question.
>>>>>
>>>>> But regardless of the results, I will adjust the script to  
>>>>> reflect that
>>>>> change. The script should not rule the HTML export and it will  
>>>>> be an
>>>>> easy thing to do.
>>>>
>>>> But I do want to hear any counter arguments you might have....
>>>>
>>>> - Carsten
>>>>
>>>>>
>>>>> Sebastian
>>>>>
>>>>>
>>>>>
>>>>>> - Carsten
>>>>>>
>>>>>>
>>>>>> On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:
>>>>>>
>>>>>>> El dv, mar 27 2009, Sebastian Rose va escriure:
>>>>>>>>
>>>>>>>> What we have now, just as Carstens said:
>>>>>>>>
>>>>>>>> # <<human-readable>>
>>>>>>>> * Section B
>>>>>>>>
>>>>>>>> Creates this headline in HTML:
>>>>>>>>
>>>>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></
>>>>>>>> a>2 Section B
>>>>>>>> </h2>
>>>>>>>>
>>>>>>>> This is enough for all the use cases I can think of.
>>>>>>>>
>>>>>>>
>>>>>>> Yes, this is enough except for two things:
>>>>>>> 1. The TOC still links to #sec-2 and the user can't change that
>>>>>>> 2. Your syntax doesn't fold very well in the outliner. I mean:  
>>>>>>> if you use
>>>>>>>
>>>>>>>> # <<human-readable>>
>>>>>>>> * Section B
>>>>>>>
>>>>>>> then the comment appears at the end of the previous section,  
>>>>>>> and you can
>>>>>>> miss
>>>>>>> it when you are viewing the heading „Section B“. I  would swap  
>>>>>>> both lines
>>>>>>> (solution 1):
>>>>>>>
>>>>>>>> * Section B
>>>>>>>> # <<human-readable>>
>>>>>>>
>>>>>>> But since there are already LOGBOOK drawers under the heading,  
>>>>>>> it would be
>>>>>>> a
>>>>>>> lot clearer to use a property, like EXPORT_ID (solution 2):
>>>>>>>
>>>>>>>> * Section B
>>>>>>>> :PROPERTIES:
>>>>>>>> :EXPORT_ID: human-readable
>>>>>>>> :END:
>>>>>>>
>>>>>>>
>>>>>>> In this way, the TOC can reliably find the EXPORT_ID, and then  
>>>>>>> generate:
>>>>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></
>>>>>>>> a>2 Section B
>>>>>>>> </h2>
>>>>>>>
>>>>>>> (You could also leave *just* the human-readable id, but having  
>>>>>>> two is not
>>>>>>> bad.
>>>>>>>
>>>>>>>
>>>>>>> I would prefer solution 1, but I don't because I'm not sure  
>>>>>>> that the TOC
>>>>>>> can
>>>>>>> find the ID if it is written as a comment anywhere under  the  
>>>>>>> heading (and
>>>>>>> together with other things).
>>>>>>>
>>>>>>> Solution 2 involves thus: a new property to specify the human-
>>>>>>> readable entry ID, which will be used to link to the entry.  
>>>>>>> The automatic
>>>>>>> ID
>>>>>>> (#sec-2) will still work for all entrys.
>>>>>>>
>>>>>>>
>>>>>>>>
>>>>>>>> * Distinguishing automatic and human readable IDs
>>>>>>>>
>>>>>>>> One thing I like is, that we now _can_ distinguish the
>>>>>>>> `human-readable-target' (human readable) from the  
>>>>>>>> `sec-2' (not human
>>>>>>>> readable and not context related) using a regular expression.
>>>>>>>>
>>>>>>>> In org-info.js, I can now prefere the human readable ID in  
>>>>>>>> <a> from an
>>>>>>>> automatic created one, and thus use that to create the links  
>>>>>>>> for `l'
>>>>>>>> and `L'. The same holds true for other programming languages  
>>>>>>>> and
>>>>>>>> parsers.
>>>>>>>>
>>>>>>>> If we open the <h3>'s ID for user defined values (bad), we  
>>>>>>>> can not
>>>>>>>> distinguish those ID's using a regular expression and there  
>>>>>>>> is no way
>>>>>>>> to detect the human readable one. There will be no way to  
>>>>>>>> _know_ that
>>>>>>>> the <a>'s ID is the prefered one used for human readable links.
>>>>>>>>
>>>>>>>
>>>>>>> Solution 2 doesn't break the parsing techniques you use; in  
>>>>>>> fact it can
>>>>>>> also
>>>>>>> make clearer which ID is the human readable one and which  one  
>>>>>>> not.
>>>>>>>
>>>>>>>
>>>>>>> This is not extremely important; just useful:
>>>>>>> - for pages with many incoming links from external sites
>>>>>>> - to ensure link integrity (now you can't assure that links  
>>>>>>> will still
>>>>>>> work
>>>>>>> in
>>>>>>> 1 year ... or in some weeks)
>>>>>>> - to avoid that HTML visitors get directed to a wrong section  
>>>>>>> and can't
>>>>>>> find
>>>>>>> what they searched
>>>>>>>
>>>>>>>
>>>>>>> Greetings,
>>>>>>> Daniel
>>>>>>>
>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> Emacs-orgmode mailing list
>>>>>>> Remember: use `Reply All' to send replies to the list.
>>>>>>> Emacs-orgmode@gnu.org
>>>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>>>
>>>>>
>>>>> --
>>>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
>>>>> Hannover
>>>>> Tel.:  +49 (0)511 - 36 58 472
>>>>> Fax:   +49 (0)1805 - 233633 - 11044
>>>>> mobil: +49 (0)173 - 83 93 417
>>>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>>>> Http:  www.emma-stil.de
>>>>
>>>
>>> --
>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
>>> Hannover
>>> Tel.:  +49 (0)511 - 36 58 472
>>> Fax:   +49 (0)1805 - 233633 - 11044
>>> mobil: +49 (0)173 - 83 93 417
>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>> Http:  www.emma-stil.de
>>
>
> -- 
> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
> Hannover
> Tel.:  +49 (0)511 - 36 58 472
> Fax:   +49 (0)1805 - 233633 - 11044
> mobil: +49 (0)173 - 83 93 417
> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
> Http:  www.emma-stil.de

Re: Re: Custom entry IDs in HTML export

[Sebastian Rose]

Carsten Dominik <carsten.dominik@gmail.com> writes:
> On Apr 16, 2009, at 10:50 PM, Sebastian Rose wrote:
>
>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>> Hi Sebastian,
>>>
>>> On Apr 16, 2009, at 3:14 PM, Sebastian Rose wrote:
>>>
>>>> Hm - counter arguments?
>>>>
>>>> The only counter argument is, that hand made IDs for links are prone to
>>>> error. But that risk should be up to the user.
>>>
>>> Yes.  and during the export, I can actually check and throw a warning or an
>>> error if the same custom ID shows up twice.
>>>
>>>>
>>>> I actually changed my mind a little in this concern.
>>>>
>>>> If the user clicks a section link in the toc to jump to a section, he
>>>> can bookmark the page with exactly that jump target. If the jump target
>>>> (the ID) is human readable, the bookmark is more verbose.
>>>
>>> Yes, this is really the best application.  Also, when hovering over internal
>>> links, it is helpful if the link displays the human-readable  form.
>>>
>>>> Just one wish:
>>>>
>>>> The containers should reflect that change (HRID = human readable id):
>>>>
>>>> <div   id="outline-container-HRID">
>>>> <h4  id="HRID">                   headline    </h4>
>>>> <div id="outline-text-HRID">
>>>>   sections content...
>>>> </div>
>>>> </div>
>>>
>>>
>>> Sure, we can do this.  I would then add sec-xxx as one
>>> of the alternative anchors as well.
>>>
>>> However:  If I make the structure as you indicate above,
>>> do I understand correctly that the structure of a section without a
>>> human-readable id should be changed to this:
>>>
>>> <div   id="outline-container-sec-1.1">
>>> <h4  id="sec-1.1">                   headline    </h4>
>>> <div id="outline-text-sec-1.1">
>>>   sections content...
>>> </div>
>>> </div>
>>>
>>>
>>> Note the "sec-" which is added to the stuff that currently
>>> defines the structure.
>>
>>
>>
>> I considered the `sec-' part of the automatic IDs.
>>
>> In either case I'd have to adjust org-info.js. So why not go for the
>> human readable IDs without `sec-'?
>>
>>
>> Right now we have:
>>
>> <div id="outline-container-2" class="outline-2">
>> <h2 id="sec-2"><span class="section-number-2">2</span> Things I want to find
>> out </h2>
>> <div class="outline-text-2" id="text-2">
>>
>> The `sec-' part is in the headlines ID only.
>
>
> Why?  Because this introduced a parsing inconsistency for you between automatic
> and custom IDs.  Because for the automatic ones, you need to  strip "sec-" to
> retrieve the correct suffix for the container etc  names.  With the custom IDs,
> no such stripping should be done.  Does  this not make things harder?
>
> - Carsten


That's the way it is _now_. The structure above is taken from one of my
exported org-files. But it's not that hard to strip `sec-' :)

Now the scanning considers `sec-' a prefix - just like
`outline-container-' and `outline-text-'.


But in the future:


If we now plan to use human readable IDs in the TOC, those IDs would be
the IDs of the section heading. That's why those IDs should have no
`sec-' prefix.

Otherwise, bookmark URLs would not be what we want them:

   http://orgmode.org/org-faq.php#sec-isearch-in-links

 instead of

   http://orgmode.org/org-faq.php#isearch-in-links



Automatic IDs on the other hand must have a prefix, since an ID may
_not_ start with a number.


So wouldn't it make sense, to change the IDs of the containers this way:

  Case _automatic_:

       <div id="outline-container-sec-1.1" ... >
         <h3 id="sec-1.1"> .... </h3>
         <div id="outline-text-sec-1.1" ... >
         ....
         </div>
       </div>

  Case _human-readable_:

       <div id="outline-container-isearch-in-links" ... >
         <h3 id="isearch-in-links"> .... </h3>
         <div id="outline-text-isearch-in-links" ... >
         ....
         </div>
       </div>

??


  Sebastian



>>
>>
>>
>>   Sebastian
>>
>>
>>
>>
>>>> That way the script would keep working with older pages.
>>>> Automatic IDs and human readable ones could be mixed.
>>>>
>>>>
>>>> The '<a id="">' anchors are scanned anyway, as are all jump targets in
>>>> the page.
>>>
>>> Yes, you implemented that some time ago, I remember.
>>>
>>>>
>>>> Maybe this is even the point to re-work the parser of org-info.js to
>>>> become independent of the TOC at all. The script could search for
>>>> headings instead. That's more work, but the script would then work for
>>>> all HTML pages with a structure similar to the org-export's one:
>>>
>>> So this would mean, we could read web pages with your java
>>> support even if those webpages were not created with Org?
>>> Pretty cool.
>>>
>>>> <div id=""><hx id=""></hx><div>content</div></div>
>>>>
>>>> but I could postpone this, if you fullfill my wish above.
>>>
>>>
>>> Best wishes
>>>
>>> - Carsten
>>>
>>>>
>>>>
>>>> Best wishes
>>>>
>>>> Sebastian
>>>>
>>>>
>>>>
>>>>
>>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>>> On Apr 16, 2009, at 10:50 AM, Sebastian Rose wrote:
>>>>>
>>>>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>>>>> Hi Sebastian,
>>>>>>>
>>>>>>> I kind of like the idea to have a property that can be
>>>>>>> used to set an ID, as an alternative to the <<target>>
>>>>>>> notation.  Actually, using a property seems a lot cleaner,
>>>>>>> thanks for coming up with this idea, Daniel.
>>>>>>>
>>>>>>> I can also follow the reasoning that it is useful to have
>>>>>>> the table of contents link to the human-readable id, because
>>>>>>> it provides a general, simple workflow to retrieve a link that
>>>>>>> will persist through changes of the document.  This workflow
>>>>>>> was described also by Bernt earlier in this thread.
>>>>>>>
>>>>>>> Finally, I also agree that the main id in the <h3> tag
>>>>>>> should be the automatically generated one because this is
>>>>>>> best for automatic processing and because of all the arguments
>>>>>>> you have presented.
>>>>>>>
>>>>>>> Would it cause problems for org-info.js if the toc points to
>>>>>>> a user specified anchor in the headline, instead of the main
>>>>>>> ID that is inside the <h3> tag?  THis would really be the only
>>>>>>> required change.
>>>>>>
>>>>>>
>>>>>> I'll have to test this before I can give a final answer to this
>>>>>> question.
>>>>>>
>>>>>> But regardless of the results, I will adjust the script to reflect that
>>>>>> change. The script should not rule the HTML export and it will be an
>>>>>> easy thing to do.
>>>>>
>>>>> But I do want to hear any counter arguments you might have....
>>>>>
>>>>> - Carsten
>>>>>
>>>>>>
>>>>>> Sebastian
>>>>>>
>>>>>>
>>>>>>
>>>>>>> - Carsten
>>>>>>>
>>>>>>>
>>>>>>> On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:
>>>>>>>
>>>>>>>> El dv, mar 27 2009, Sebastian Rose va escriure:
>>>>>>>>>
>>>>>>>>> What we have now, just as Carstens said:
>>>>>>>>>
>>>>>>>>> # <<human-readable>>
>>>>>>>>> * Section B
>>>>>>>>>
>>>>>>>>> Creates this headline in HTML:
>>>>>>>>>
>>>>>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></
>>>>>>>>> a>2 Section B
>>>>>>>>> </h2>
>>>>>>>>>
>>>>>>>>> This is enough for all the use cases I can think of.
>>>>>>>>>
>>>>>>>>
>>>>>>>> Yes, this is enough except for two things:
>>>>>>>> 1. The TOC still links to #sec-2 and the user can't change that
>>>>>>>> 2. Your syntax doesn't fold very well in the outliner. I mean: if you
>>>>>>>> use
>>>>>>>>
>>>>>>>>> # <<human-readable>>
>>>>>>>>> * Section B
>>>>>>>>
>>>>>>>> then the comment appears at the end of the previous section, and you can
>>>>>>>> miss
>>>>>>>> it when you are viewing the heading „Section B“. I  would swap both
>>>>>>>> lines
>>>>>>>> (solution 1):
>>>>>>>>
>>>>>>>>> * Section B
>>>>>>>>> # <<human-readable>>
>>>>>>>>
>>>>>>>> But since there are already LOGBOOK drawers under the heading, it would
>>>>>>>> be
>>>>>>>> a
>>>>>>>> lot clearer to use a property, like EXPORT_ID (solution 2):
>>>>>>>>
>>>>>>>>> * Section B
>>>>>>>>> :PROPERTIES:
>>>>>>>>> :EXPORT_ID: human-readable
>>>>>>>>> :END:
>>>>>>>>
>>>>>>>>
>>>>>>>> In this way, the TOC can reliably find the EXPORT_ID, and then generate:
>>>>>>>>> <h2 id="sec-2"><a name="human-readable" id="human-readable"></
>>>>>>>>> a>2 Section B
>>>>>>>>> </h2>
>>>>>>>>
>>>>>>>> (You could also leave *just* the human-readable id, but having two is
>>>>>>>> not
>>>>>>>> bad.
>>>>>>>>
>>>>>>>>
>>>>>>>> I would prefer solution 1, but I don't because I'm not sure that the TOC
>>>>>>>> can
>>>>>>>> find the ID if it is written as a comment anywhere under  the heading
>>>>>>>> (and
>>>>>>>> together with other things).
>>>>>>>>
>>>>>>>> Solution 2 involves thus: a new property to specify the human-
>>>>>>>> readable entry ID, which will be used to link to the entry. The
>>>>>>>> automatic
>>>>>>>> ID
>>>>>>>> (#sec-2) will still work for all entrys.
>>>>>>>>
>>>>>>>>
>>>>>>>>>
>>>>>>>>> * Distinguishing automatic and human readable IDs
>>>>>>>>>
>>>>>>>>> One thing I like is, that we now _can_ distinguish the
>>>>>>>>> `human-readable-target' (human readable) from the `sec-2' (not human
>>>>>>>>> readable and not context related) using a regular expression.
>>>>>>>>>
>>>>>>>>> In org-info.js, I can now prefere the human readable ID in <a> from an
>>>>>>>>> automatic created one, and thus use that to create the links for `l'
>>>>>>>>> and `L'. The same holds true for other programming languages and
>>>>>>>>> parsers.
>>>>>>>>>
>>>>>>>>> If we open the <h3>'s ID for user defined values (bad), we can not
>>>>>>>>> distinguish those ID's using a regular expression and there is no way
>>>>>>>>> to detect the human readable one. There will be no way to _know_ that
>>>>>>>>> the <a>'s ID is the prefered one used for human readable links.
>>>>>>>>>
>>>>>>>>
>>>>>>>> Solution 2 doesn't break the parsing techniques you use; in fact it can
>>>>>>>> also
>>>>>>>> make clearer which ID is the human readable one and which  one not.
>>>>>>>>
>>>>>>>>
>>>>>>>> This is not extremely important; just useful:
>>>>>>>> - for pages with many incoming links from external sites
>>>>>>>> - to ensure link integrity (now you can't assure that links will still
>>>>>>>> work
>>>>>>>> in
>>>>>>>> 1 year ... or in some weeks)
>>>>>>>> - to avoid that HTML visitors get directed to a wrong section and can't
>>>>>>>> find
>>>>>>>> what they searched
>>>>>>>>
>>>>>>>>
>>>>>>>> Greetings,
>>>>>>>> Daniel
>>>>>>>>
>>>>>>>>
>>>>>>>> _______________________________________________
>>>>>>>> Emacs-orgmode mailing list
>>>>>>>> Remember: use `Reply All' to send replies to the list.
>>>>>>>> Emacs-orgmode@gnu.org
>>>>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>>>>
>>>>>>
>>>>>> --
>>>>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
>>>>>> Tel.:  +49 (0)511 - 36 58 472
>>>>>> Fax:   +49 (0)1805 - 233633 - 11044
>>>>>> mobil: +49 (0)173 - 83 93 417
>>>>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>>>>> Http:  www.emma-stil.de
>>>>>
>>>>
>>>> --
>>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
>>>> Tel.:  +49 (0)511 - 36 58 472
>>>> Fax:   +49 (0)1805 - 233633 - 11044
>>>> mobil: +49 (0)173 - 83 93 417
>>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>>> Http:  www.emma-stil.de
>>>
>>
>> --
>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
>> Tel.:  +49 (0)511 - 36 58 472
>> Fax:   +49 (0)1805 - 233633 - 11044
>> mobil: +49 (0)173 - 83 93 417
>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>> Http:  www.emma-stil.de
>

-- 
Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449 Hannover
Tel.:  +49 (0)511 - 36 58 472
Fax:   +49 (0)1805 - 233633 - 11044
mobil: +49 (0)173 - 83 93 417
Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
Http:  www.emma-stil.de

Re: Re: Custom entry IDs in HTML export

[Carsten Dominik]

On Apr 17, 2009, at 12:37 AM, Sebastian Rose wrote:

> Carsten Dominik <carsten.dominik@gmail.com> writes:
>> On Apr 16, 2009, at 10:50 PM, Sebastian Rose wrote:
>>
>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>> Hi Sebastian,
>>>>
>>>> On Apr 16, 2009, at 3:14 PM, Sebastian Rose wrote:
>>>>
>>>>> Hm - counter arguments?
>>>>>
>>>>> The only counter argument is, that hand made IDs for links are  
>>>>> prone to
>>>>> error. But that risk should be up to the user.
>>>>
>>>> Yes.  and during the export, I can actually check and throw a  
>>>> warning or an
>>>> error if the same custom ID shows up twice.
>>>>
>>>>>
>>>>> I actually changed my mind a little in this concern.
>>>>>
>>>>> If the user clicks a section link in the toc to jump to a  
>>>>> section, he
>>>>> can bookmark the page with exactly that jump target. If the jump  
>>>>> target
>>>>> (the ID) is human readable, the bookmark is more verbose.
>>>>
>>>> Yes, this is really the best application.  Also, when hovering  
>>>> over internal
>>>> links, it is helpful if the link displays the human-readable  form.
>>>>
>>>>> Just one wish:
>>>>>
>>>>> The containers should reflect that change (HRID = human readable  
>>>>> id):
>>>>>
>>>>> <div   id="outline-container-HRID">
>>>>> <h4  id="HRID">                   headline    </h4>
>>>>> <div id="outline-text-HRID">
>>>>>  sections content...
>>>>> </div>
>>>>> </div>
>>>>
>>>>
>>>> Sure, we can do this.  I would then add sec-xxx as one
>>>> of the alternative anchors as well.
>>>>
>>>> However:  If I make the structure as you indicate above,
>>>> do I understand correctly that the structure of a section without a
>>>> human-readable id should be changed to this:
>>>>
>>>> <div   id="outline-container-sec-1.1">
>>>> <h4  id="sec-1.1">                   headline    </h4>
>>>> <div id="outline-text-sec-1.1">
>>>>  sections content...
>>>> </div>
>>>> </div>
>>>>
>>>>
>>>> Note the "sec-" which is added to the stuff that currently
>>>> defines the structure.
>>>
>>>
>>>
>>> I considered the `sec-' part of the automatic IDs.
>>>
>>> In either case I'd have to adjust org-info.js. So why not go for the
>>> human readable IDs without `sec-'?
>>>
>>>
>>> Right now we have:
>>>
>>> <div id="outline-container-2" class="outline-2">
>>> <h2 id="sec-2"><span class="section-number-2">2</span> Things I  
>>> want to find
>>> out </h2>
>>> <div class="outline-text-2" id="text-2">
>>>
>>> The `sec-' part is in the headlines ID only.
>>
>>
>> Why?  Because this introduced a parsing inconsistency for you  
>> between automatic
>> and custom IDs.  Because for the automatic ones, you need to  strip  
>> "sec-" to
>> retrieve the correct suffix for the container etc  names.  With the  
>> custom IDs,
>> no such stripping should be done.  Does  this not make things harder?
>>
>> - Carsten
>
>
> That's the way it is _now_. The structure above is taken from one of  
> my
> exported org-files. But it's not that hard to strip `sec-' :)
>
> Now the scanning considers `sec-' a prefix - just like
> `outline-container-' and `outline-text-'.
>
>
> But in the future:
>
>
> If we now plan to use human readable IDs in the TOC, those IDs would  
> be
> the IDs of the section heading. That's why those IDs should have no
> `sec-' prefix.
>
> Otherwise, bookmark URLs would not be what we want them:
>
>   http://orgmode.org/org-faq.php#sec-isearch-in-links
>
> instead of
>
>   http://orgmode.org/org-faq.php#isearch-in-links
>
>
>
> Automatic IDs on the other hand must have a prefix, since an ID may
> _not_ start with a number.
>
>
> So wouldn't it make sense, to change the IDs of the containers this  
> way:
>
>  Case _automatic_:
>
>       <div id="outline-container-sec-1.1" ... >
>         <h3 id="sec-1.1"> .... </h3>
>         <div id="outline-text-sec-1.1" ... >
>         ....
>         </div>
>       </div>
>
>  Case _human-readable_:
>
>       <div id="outline-container-isearch-in-links" ... >
>         <h3 id="isearch-in-links"> .... </h3>
>         <div id="outline-text-isearch-in-links" ... >
>         ....
>         </div>
>       </div>

Yes, it does make sense.  t only introduces on tiny restriction:  A  
human-readable ID may not be something like sec-555, but that is  
reasonable, we can document and enforce this.

OK. This is what I have done now.  You need to use the property  
CUSTOM_ID.
Please do some testing, and then I will document this change.

Daniel, could you help testing, please?

- Carsten

>
> ??
>
>
>  Sebastian
>
>
>
>>>
>>>
>>>
>>>  Sebastian
>>>
>>>
>>>
>>>
>>>>> That way the script would keep working with older pages.
>>>>> Automatic IDs and human readable ones could be mixed.
>>>>>
>>>>>
>>>>> The '<a id="">' anchors are scanned anyway, as are all jump  
>>>>> targets in
>>>>> the page.
>>>>
>>>> Yes, you implemented that some time ago, I remember.
>>>>
>>>>>
>>>>> Maybe this is even the point to re-work the parser of org- 
>>>>> info.js to
>>>>> become independent of the TOC at all. The script could search for
>>>>> headings instead. That's more work, but the script would then  
>>>>> work for
>>>>> all HTML pages with a structure similar to the org-export's one:
>>>>
>>>> So this would mean, we could read web pages with your java
>>>> support even if those webpages were not created with Org?
>>>> Pretty cool.
>>>>
>>>>> <div id=""><hx id=""></hx><div>content</div></div>
>>>>>
>>>>> but I could postpone this, if you fullfill my wish above.
>>>>
>>>>
>>>> Best wishes
>>>>
>>>> - Carsten
>>>>
>>>>>
>>>>>
>>>>> Best wishes
>>>>>
>>>>> Sebastian
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>>>> On Apr 16, 2009, at 10:50 AM, Sebastian Rose wrote:
>>>>>>
>>>>>>> Carsten Dominik <carsten.dominik@gmail.com> writes:
>>>>>>>> Hi Sebastian,
>>>>>>>>
>>>>>>>> I kind of like the idea to have a property that can be
>>>>>>>> used to set an ID, as an alternative to the <<target>>
>>>>>>>> notation.  Actually, using a property seems a lot cleaner,
>>>>>>>> thanks for coming up with this idea, Daniel.
>>>>>>>>
>>>>>>>> I can also follow the reasoning that it is useful to have
>>>>>>>> the table of contents link to the human-readable id, because
>>>>>>>> it provides a general, simple workflow to retrieve a link that
>>>>>>>> will persist through changes of the document.  This workflow
>>>>>>>> was described also by Bernt earlier in this thread.
>>>>>>>>
>>>>>>>> Finally, I also agree that the main id in the <h3> tag
>>>>>>>> should be the automatically generated one because this is
>>>>>>>> best for automatic processing and because of all the arguments
>>>>>>>> you have presented.
>>>>>>>>
>>>>>>>> Would it cause problems for org-info.js if the toc points to
>>>>>>>> a user specified anchor in the headline, instead of the main
>>>>>>>> ID that is inside the <h3> tag?  THis would really be the only
>>>>>>>> required change.
>>>>>>>
>>>>>>>
>>>>>>> I'll have to test this before I can give a final answer to this
>>>>>>> question.
>>>>>>>
>>>>>>> But regardless of the results, I will adjust the script to  
>>>>>>> reflect that
>>>>>>> change. The script should not rule the HTML export and it will  
>>>>>>> be an
>>>>>>> easy thing to do.
>>>>>>
>>>>>> But I do want to hear any counter arguments you might have....
>>>>>>
>>>>>> - Carsten
>>>>>>
>>>>>>>
>>>>>>> Sebastian
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>> - Carsten
>>>>>>>>
>>>>>>>>
>>>>>>>> On Mar 30, 2009, at 1:49 PM, Daniel Clemente wrote:
>>>>>>>>
>>>>>>>>> El dv, mar 27 2009, Sebastian Rose va escriure:
>>>>>>>>>>
>>>>>>>>>> What we have now, just as Carstens said:
>>>>>>>>>>
>>>>>>>>>> # <<human-readable>>
>>>>>>>>>> * Section B
>>>>>>>>>>
>>>>>>>>>> Creates this headline in HTML:
>>>>>>>>>>
>>>>>>>>>> <h2 id="sec-2"><a name="human-readable" id="human- 
>>>>>>>>>> readable"></
>>>>>>>>>> a>2 Section B
>>>>>>>>>> </h2>
>>>>>>>>>>
>>>>>>>>>> This is enough for all the use cases I can think of.
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Yes, this is enough except for two things:
>>>>>>>>> 1. The TOC still links to #sec-2 and the user can't change  
>>>>>>>>> that
>>>>>>>>> 2. Your syntax doesn't fold very well in the outliner. I  
>>>>>>>>> mean: if you
>>>>>>>>> use
>>>>>>>>>
>>>>>>>>>> # <<human-readable>>
>>>>>>>>>> * Section B
>>>>>>>>>
>>>>>>>>> then the comment appears at the end of the previous section,  
>>>>>>>>> and you can
>>>>>>>>> miss
>>>>>>>>> it when you are viewing the heading „Section B“. I  would  
>>>>>>>>> swap both
>>>>>>>>> lines
>>>>>>>>> (solution 1):
>>>>>>>>>
>>>>>>>>>> * Section B
>>>>>>>>>> # <<human-readable>>
>>>>>>>>>
>>>>>>>>> But since there are already LOGBOOK drawers under the  
>>>>>>>>> heading, it would
>>>>>>>>> be
>>>>>>>>> a
>>>>>>>>> lot clearer to use a property, like EXPORT_ID (solution 2):
>>>>>>>>>
>>>>>>>>>> * Section B
>>>>>>>>>> :PROPERTIES:
>>>>>>>>>> :EXPORT_ID: human-readable
>>>>>>>>>> :END:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> In this way, the TOC can reliably find the EXPORT_ID, and  
>>>>>>>>> then generate:
>>>>>>>>>> <h2 id="sec-2"><a name="human-readable" id="human- 
>>>>>>>>>> readable"></
>>>>>>>>>> a>2 Section B
>>>>>>>>>> </h2>
>>>>>>>>>
>>>>>>>>> (You could also leave *just* the human-readable id, but  
>>>>>>>>> having two is
>>>>>>>>> not
>>>>>>>>> bad.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> I would prefer solution 1, but I don't because I'm not sure  
>>>>>>>>> that the TOC
>>>>>>>>> can
>>>>>>>>> find the ID if it is written as a comment anywhere under   
>>>>>>>>> the heading
>>>>>>>>> (and
>>>>>>>>> together with other things).
>>>>>>>>>
>>>>>>>>> Solution 2 involves thus: a new property to specify the human-
>>>>>>>>> readable entry ID, which will be used to link to the entry.  
>>>>>>>>> The
>>>>>>>>> automatic
>>>>>>>>> ID
>>>>>>>>> (#sec-2) will still work for all entrys.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> * Distinguishing automatic and human readable IDs
>>>>>>>>>>
>>>>>>>>>> One thing I like is, that we now _can_ distinguish the
>>>>>>>>>> `human-readable-target' (human readable) from the  
>>>>>>>>>> `sec-2' (not human
>>>>>>>>>> readable and not context related) using a regular expression.
>>>>>>>>>>
>>>>>>>>>> In org-info.js, I can now prefere the human readable ID in  
>>>>>>>>>> <a> from an
>>>>>>>>>> automatic created one, and thus use that to create the  
>>>>>>>>>> links for `l'
>>>>>>>>>> and `L'. The same holds true for other programming  
>>>>>>>>>> languages and
>>>>>>>>>> parsers.
>>>>>>>>>>
>>>>>>>>>> If we open the <h3>'s ID for user defined values (bad), we  
>>>>>>>>>> can not
>>>>>>>>>> distinguish those ID's using a regular expression and there  
>>>>>>>>>> is no way
>>>>>>>>>> to detect the human readable one. There will be no way to  
>>>>>>>>>> _know_ that
>>>>>>>>>> the <a>'s ID is the prefered one used for human readable  
>>>>>>>>>> links.
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Solution 2 doesn't break the parsing techniques you use; in  
>>>>>>>>> fact it can
>>>>>>>>> also
>>>>>>>>> make clearer which ID is the human readable one and which   
>>>>>>>>> one not.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> This is not extremely important; just useful:
>>>>>>>>> - for pages with many incoming links from external sites
>>>>>>>>> - to ensure link integrity (now you can't assure that links  
>>>>>>>>> will still
>>>>>>>>> work
>>>>>>>>> in
>>>>>>>>> 1 year ... or in some weeks)
>>>>>>>>> - to avoid that HTML visitors get directed to a wrong  
>>>>>>>>> section and can't
>>>>>>>>> find
>>>>>>>>> what they searched
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Greetings,
>>>>>>>>> Daniel
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> _______________________________________________
>>>>>>>>> Emacs-orgmode mailing list
>>>>>>>>> Remember: use `Reply All' to send replies to the list.
>>>>>>>>> Emacs-orgmode@gnu.org
>>>>>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
>>>>>>> Hannover
>>>>>>> Tel.:  +49 (0)511 - 36 58 472
>>>>>>> Fax:   +49 (0)1805 - 233633 - 11044
>>>>>>> mobil: +49 (0)173 - 83 93 417
>>>>>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>>>>>> Http:  www.emma-stil.de
>>>>>>
>>>>>
>>>>> --
>>>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
>>>>> Hannover
>>>>> Tel.:  +49 (0)511 - 36 58 472
>>>>> Fax:   +49 (0)1805 - 233633 - 11044
>>>>> mobil: +49 (0)173 - 83 93 417
>>>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>>>> Http:  www.emma-stil.de
>>>>
>>>
>>> --
>>> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
>>> Hannover
>>> Tel.:  +49 (0)511 - 36 58 472
>>> Fax:   +49 (0)1805 - 233633 - 11044
>>> mobil: +49 (0)173 - 83 93 417
>>> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
>>> Http:  www.emma-stil.de
>>
>
> -- 
> Sebastian Rose, EMMA STIL - mediendesign, Niemeyerstr.6, 30449  
> Hannover
> Tel.:  +49 (0)511 - 36 58 472
> Fax:   +49 (0)1805 - 233633 - 11044
> mobil: +49 (0)173 - 83 93 417
> Email: s.rose@emma-stil.de, sebastian_rose@gmx.de
> Http:  www.emma-stil.de