search

sander / code-illuminated

Automatically exported from code.google.com/p/code-illuminated
0 stars 0 forks source link

Adding internal link #7

Open GoogleCodeExporter opened 9 years ago

GoogleCodeExporter commented 9 years ago 
At least one thing is missing in "Code Illuminated" to improve use, to be
closer to wiki or to reduce the gap with "Literate Programming": an easy
internal linking facility to target one part of the commented JS code.

Something like [[wikiPage]].

As far as wikiCreole is concerned, redactors should be able to write
[[bipbip]], and readers could follow the link which should lead them to
some entry "bipbip".
But in "Code Illuminated", wikiCreole is mostly used for formating and not
for internal linking. If you write[[bipbip]] in a js file, there would be a
link in the formated text, ok, and if you follow that link, it would lead
you to a file "bipbip" (if it exists) ((maybe [[bipbip.js]] would have been
better, for that purpose)) but unfortunaltly, it would not format it! And
you do not have targetet one part of the file.

The main problem, from my point of view, is that files does not corespond
to the notion of entry in a wiki or chunk of code in "Literate Programming".

What I would like to have, when I follow a link [[bipbip]], is the part of
a file (A file?) related to "bipbip". 
So, first remark, which file? In fact, "Code Illuminated" works with a
collection of sources/files, so entry "bipbip" should be associated to a
file. Why not write [[theRightFile.js#bipbip]]?
I've chosen the metacharacter "#" as a reference to html anchor. It could
be changed.

Second, I would like to have a formatted text, so we have to pass through
the index.html (or any html file you used as the basis of your
documentation), if we follow the way "Code Illuminated"
works we should write [[index.html#theRightFile.js#bipbip]]

Then, finally, "Code Illuminated" or html should understand what we have
written...

Here a function which try to find 'bipbip' (or anything you want) in the
headers (h1 or h2) of a file, and focus on it.
I've put it in the list of user-post-processed-functions:
App.processors = [
  function (docs) {
    if (document.location.hash) {
      var d =
document.location.hash.slice(1,document.location.hash.length).indexOf('#');
      if ( d > 1 ) {
        var g =
document.location.hash.slice(2+d,document.location.hash.length); //the
target find in the url
        if ($(docs).find('h1:contains("'+g+'")').length) {
          var n = $(docs).find('h1:contains("'+g+'")')[0].innerHTML //the target
find in the file
          $(docs).find('h1:contains("' + g + '")')[0].innerHTML = '<a id="' + n +
'" name="' + n + '">' + n + '</a>';
                  $('#' + n).focus();
          }
        else if ($(docs).find('h2:contains("'+g+'")').length) {
          var n = $(docs).find('h2:contains("'+g+'")')[0].innerHTML;
          $(docs).find('h2:contains("' + g + '")')[0].innerHTML = '<a id="' + n +
'" name="' + n + '">' + n + '</a>';
                  $('#' + n).focus();
          }
        }
      }
    }
    ];

There is a working example there:
http://www.noe-kaleidoscope.org/public/people/DenisB/EDBA/docsTables.html
follows normal link: xMail.js
then the new special internal link: docsTables.html#login.js#IdUser

Possible improvment :
* change the way to indicate the target #, @, ->, ?, (), ...?
(personnaly, I would prefer docsTables.html?login.js#IdUser)
* automatically insert the name of the base file "index.html" + "#"
(but it should be done during the parsing phase)
* the target "bipbip" is find via $('h1:contains("bipbip")') (or else 
$('h2:contains("bipbip")')) It could be improved (a css selector? xpath? or
... but this is not the philosophy of wiki)

and then, why not add it to "the core code of Code Illuminated"

Original issue reported on code.google.com by Denis.Bo...@imag.fr on 16 Feb 2009 at 6:29

GoogleCodeExporter commented 9 years ago 
hum ...
http://www.noe-kaleidoscope.org/public/people/DenisB/EDBA/Tables/docsTables.html
is better (sorry)

Original comment by Denis.Bo...@imag.fr on 16 Feb 2009 at 6:31

GoogleCodeExporter commented 9 years ago 
It worked in ff 2.XXX but not in ff 3.XXX (in ff 3.XX the <a> do not focus), 
I'll
have to change a bit (maybe add a small <input> or something else which do 
focus)

Original comment by Denis.Bo...@imag.fr on 18 Feb 2009 at 12:45

GoogleCodeExporter commented 9 years ago 
[[#mypage.js]] or [[#mypage.js|mypage]] are rendered correctly and, if you 
follow 
the link, the target page is rendered as well.

About adding an internal link I read the section Inner Page Anchors:

http://www.wikicreole.org/wiki/Talk.Links

My suggestion is the following 

[[#1]] -> <a name='1' /> 

as stated in that talk and 

[[#1|text]] -> <a name='1' href='#1'>text</a> 

Just adding to [[...]] tag the name attribute, it would be an automatic anchor 
for
another link.

I think this changes should be done in wiki parser, but I will give a look in 
the
code later.

Original comment by albertos...@gmail.com on 18 Feb 2009 at 2:17

GoogleCodeExporter commented 9 years ago 
>[[#mypage.js]] or [[#mypage.js|mypage]] are rendered correctly and, 
>if you follow  the link, the target page is rendered as well.

yes, it's ok.

>About adding an internal link I read the section Inner Page Anchors:
>
>http://www.wikicreole.org/wiki/Talk.Links
>
>>My suggestion is the following 
>>
>>[[#1]] -> <a name='1' /> 
>>
>>as stated in that talk and 
>>
>>[[#1|text]] -> <a name='1' href='#1'>text</a> 
>>

I had, some more comment from the page:

>>>I'd prefer a clearer way to disambiguate anchors and links, 
>>>so that links don't need text; e.g. [[@Chater1]] for anchor and 
>>>[[#Chapter1]] or [[#Chapter1|Chapter 1]] for link.
>>

(even more true, here, because # have also some meaning in docs ...)

>Just adding to [[...]] tag the name attribute, it would be an 
>automatic anchor for another link.
>
>I think this changes should be done in wiki parser, 
>but I will give a look in the code later.

ok.

about internal : I mean internal, from the point of view of the wiki (idem for 
the
comment from wiki creole), with Code Illuminated, it means internal to some 
file in
the documentation (but which file? it is to be said somewhere), not just 
internal to
the current file. The wiki, it is the set of all files of the documentation.

Original comment by Denis.Bo...@imag.fr on 18 Feb 2009 at 2:55

GoogleCodeExporter commented 9 years ago 
bug "<a> do not focus" solved 

Tested on ff3 and chrome.

Working example:
http://www.noe-kaleidoscope.org/public/people/DenisB/EDBA/Tables/docsTables.html
follows normal link: xMail.js
then the new special internal link: docsTables.html#login.js#IdUser

Solution:

App.processors = [
  function (docs) {
    if (document.location.hash) {
      var d = document.location.hash.slice(1,document.location.hash.length).indexOf('#');
      if ( d > 1 ) {
        var g = document.location.hash.slice(2+d,document.location.hash.length);
        if ($(docs).find('h1:contains("'+g+'")').length) {
          var n = $(docs).find('h1:contains("'+g+'")')[0].innerHTML;
          $(docs).find('h1:contains("'+g+'")')[0].innerHTML= n+'<input type="text" size="1"
style="border:0px" id="focusTarget">focusTarget</input>';
          $('#focusTarget').focus();
          $(docs).find('h1:contains("'+g+'")')[0].innerHTML=n;
          }
        else if ($(docs).find('h2:contains("'+g+'")').length) {
          var n = $(docs).find('h2:contains("'+g+'")')[0].innerHTML;
          $(docs).find('h2:contains("'+g+'")')[0].innerHTML= n+'<input type="text" size="1"
style="border:0px" id="focusTarget">focusTarget</input>';
          $('#focusTarget').focus();
          $(docs).find('h2:contains("'+g+'")')[0].innerHTML=n;
          }
        }
      }
    }
    ];

Original comment by Denis.Bo...@imag.fr on 18 Feb 2009 at 3:01

GoogleCodeExporter commented 9 years ago 
about focus, a  very small improvment (I've tried to focus few lines after the 
target):

$(docs).find('h1:contains("'+g+'")')[0].innerHTML= n+'<br /><br /><br /><input
type="text" size="1" style="border:0px" id="focusTarget">focusTarget</input>';
$('#focusTarget').focus();
$(docs).find('h1:contains("'+g+'")')[0].innerHTML=n;

Original comment by Denis.Bo...@imag.fr on 19 Feb 2009 at 7:04