Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

TOCs and deeplinks for our house rules

by LanX (Bishop)
on Oct 31, 2017 at 18:17 UTC ( #1202462=monkdiscuss: print w/replies, xml ) Need Help??

Hi

I want to suggest adding linked Tables Of Content at the beginning of long pages like Markup in the Monastery

It would facilitate communication about the rules "bigly" if we were able to add deeplinks with #anchors to our posts.

See Re^3: trap signal 'exit': why I am not able to have it work?? for a demonstration of the status quo, I need to cite the paragraph because deeplinks are missing.

Cheers Rolf
(addicted to the Perl Programming Language and ☆☆☆☆ :)
Je suis Charlie!

Replies are listed 'Best First'.
Re: TOCs and deeplinks for our house rules
by RonW (Vicar) on Oct 31, 2017 at 20:37 UTC

    This would be a very good idea.

    In case it might be helpful, years ago, I wrote a Perl program to add TOCs to HTML. If I can find it, I will post it under CUFP.

    The program looks for header elements (<h1> through <h6>) and checks them for an id attribute. If there isn't one, it adds one, using a generated identifier. The text of the header elements is used for the TOC entries, which are dt elements in a dl list element. I did not implement nesting of dl lists.

Re: TOCs and deeplinks for our house rules
by kcott (Chancellor) on Nov 01, 2017 at 05:46 UTC

    G'day Lanx,

    The idea of being able to use fragment identifiers is a good one.

    Some pages have them but they're not easy to find. For instance, I can link to the section of "What shortcuts can I use for linking to other information?" which explains how to use fragment identifiers with this type of markup: [href://?node_id=43037#general|General-Purpose Linking Shortcuts] (which renders as General-Purpose Linking Shortcuts); however, you need to know that the identifiers exist on that particular page and then you have to find them. I generally use the "Inspect Element" browser tool menu option for this; another (less than optimal) method would be to search the page's source HTML code.

    Many other pages don't have such identifiers, so a first step would be to add them.

    A TOC would one way to handle this: I can certainly see benefits to doing this. When I've found what I'm looking for in a page, having an indication of the identifier at that point would be better than having to scroll back to the top to see what the TOC links to. I've seen this type of thing done with unobtrusive link text consisting of a single symbol character: § and seem to be used quite a lot; I've seen others, many with various types of arrow symbols; I don't really have a preference.

    I also think the syntax for such links needs to be made more obvious — it's virtually a hidden feature at present. As I'm writing this, I see a link for "What shortcuts can I use for linking to other information?" almost at the bottom of the page. Following that link, I then need to scroll down five screenfuls (on my 27' monitor) to find the information. Searching that page for "fragment" or "identifier" finds no matches; searching for "href:" finds it but, if you knew to search for that, you probably didn't need to (i.e. you already know the syntax).

    — Ken

      G'day kcott,

      > I also think the syntax for such links needs to be made more obvious

      I agree, but first things first!

      For the beginning now I wrote a script which generates a TOC.

      (FWIW I wrote a nodelet-hack which automatically translates literal URLs to the monastery to appropriate markup.)

      I think the monastery should also consider automatically translating self referential text to the meant markup:

      So

      http://perlmonks.org/?node_id=1202656#Textual_content:

      would become

      Re^2: TOCs and deeplinks for our house rules#Textual content:

      [href://?node_id=1202656#Textual_content:|Re^2: TOCs and deeplinks for our house rules#Textual content:]

      > having an indication of the identifier at that point would be better than having to scroll back to the top to see what the TOC links to.

      What I did now is transforming the headings to links to the original TOC entry.

      Like this you only need two clicks to get the URL in the address bar and navigating to the TOC becomes trivial:

      Cheers Rolf
      (addicted to the Perl Programming Language and ☆☆☆☆ :)
      Je suis Charlie!

Re: TOCs and deeplinks for our house rules
by ww (Archbishop) on Nov 01, 2017 at 03:56 UTC

    TOC is a good idea on this one; since I wrote the original, I edit, 7 Nov 17 will try to free up time, soonest, to add one. offer TOC draft sample for comment and review.

    FOR COMMENT: seems like a TOC with both a few keywords for each topic AND the markup needed would be appropriate... but a big PITA.

    Update, 7 Nov 17 It was! The PITA is finding an appropriate, very brief description for the various parts of the TOC (and, in this case, deciding which elements of the main text to include to best serve users!

    FWIW: Others have written technical approaches, using clever code to identify elements that may need to be included in a TOC. I went "manual" to deal with the issue I perceive (at least in the case of Markup in the Monastery; namely, that the so-called "Chapter...." headings are not, themselves, informative for someone seeking (for example) to know how to create a list. Also, when I created "Markup" originally, the various <Hn> tags were for formatting only, without due regard to nesting (I don't know of any commonly-used browser, even today, that cares) or syntactical relevance. Call me a dinosaur, but I still don't worry about that: even today, itelligibility of content trumps sytactical correctness.

    Quis custodiet ipsos custodes. Juvenal, Satires

      > seems like a TOC with both a few keywords for each topic AND the markup needed would be appropriate... but a big PITA.

      For a start:

      Hacked some code augmenting H-tags and generating a TOC:

      YMMV

      HTH! :)

      update:

      something is wrong, for a reason I do not understand yet the anchors are filtered ...

      need to check the allowed tags in the monastery... (under construction)

      produced HTML see reply here Re^3: TOCs and deeplinks for our house rules

      update

      needed extra <a name="$target"> tags

      update

      Forgot to mention, I had to change the input at some places:

      • Some h3 needed to be h4 to be properly nested
      • some heading were just examples and were indented to be ignored
      An included heading needs to start a line without leading whitespace and can't be followed by anything else but whitespace.
        replaced id with name, think id is not allowed in the monastery.

        update

        Approved HTML tags don't allow id or name attributes inside <h.> tags so I used additional <a name=""> tags.

        seems to work now:

        Some h3 needed to be h4 to be properly nested

        Sounds like your TOC generator has gone beyond mine. That great!

        FWIW, I didn't try dealing with header nesting because a lot of the HTML to be processed was very poorly written. If I had, the TOC would have looked haphazard.

      Also, when I created "Markup" originally, the various <Hn> tags were for formatting only, without due regard to nesting

      That was the problem I ran into. I chose to index any <Hn> with out nesting, using the contained text for the TOC entries. I also provided options to exclude any level of <Hn> (the default being to index all). The results were acceptable to those who used my program. (It also encouraged some to go back and improve their "section titles".)

      For a more general solution (for new pages or significantly re-worked pages), perhaps PM markup could include a toc attribute to indicate elements to be in the TOC with an option value to specify nesting level and/or TOC text.

      Examples:

      <div toc>This text will appear in the TOC at $current_nesting level</div>

      <div toc="++">This text will appear in the TOC at $current_nesting++ level</div>

      <div toc="--">Likewise, this at at $current_nesting-- level</div>

      <h3 toc="2">This text will be at TOC level 2 despite being in an H3 element</h3>

      <p toc="4,This text, after first comma, will appear in the TOC at level 4">Text not appearing in the TOC</p>

        Adding new markup is complicated*, I'd rather prefer a KISS approach, not least because of backwards compatibility.

        The only possible targets in PM is <a name="anchor-name"> so adding a parser for a magic href #toc or #notoc would already do, i.e.

        <a href="#toc" name="anchor-name">

        A new markup <toc> should have a reasonable default behaviour

        • nesting all H tags, unless excluded by linebreak
        • adding all <a name=""> tags under the last H level
        Any "filtering" features should be discussed after implementing and testing the first phase.

        In a side note: There is a tendency to mangle the concept of "keywords" into this discussion.

        IMHO that's mostly unrelated, first things first.

        FWIW PM has already a keyword nodelet, but lacks a search engine for it...

        Cheers Rolf
        (addicted to the Perl Programming Language and ☆☆☆☆ :)
        Je suis Charlie!

        *) actually I can't even locate the corresponding code, I'm volunteering to implement it if possible.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: monkdiscuss [id://1202462]
Approved by herveus
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (7)
As of 2018-06-18 11:44 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?



    Results (109 votes). Check out past polls.

    Notices?