Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

Re: TOCs and deeplinks for our house rules

by ww (Archbishop)
on Nov 01, 2017 at 03:56 UTC ( [id://1202492]=note: print w/replies, xml ) Need Help??


in reply to TOCs and deeplinks for our house rules

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

Replies are listed 'Best First'.
Re^2: TOCs and deeplinks for our house rules
by LanX (Saint) on Nov 02, 2017 at 17:28 UTC
    > 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.

        > 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.

        actually I don't know yet how to deal best with wrong nesting.

        E.g a h6 following a h4 would be ignored now (or added to the last h5 which is nonsense*)

        I don't know if it's better to

        • include the missing intermediate levels
        Or
        • ignore the heading
        A warning should be emitted anyway.

        Another nice to have would be to parse already available anchors, to allow multiple runs.

        Again the problem arises if a new anchor should be generated or the last one taken.

        I think all of this should be configurable, but so many options make this already a candidate for a proper module. ...

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

        *) actually this explains weird problems I saw with latex beamer and wrong nesting. .. cool insight into alien code.

Re^2: TOCs and deeplinks for our house rules
by RonW (Parson) on Nov 09, 2017 at 01:01 UTC
    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
Domain Nodelet?
Node Status?
node history
Node Type: note [id://1202492]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others chilling in the Monastery: (4)
As of 2024-03-29 00:51 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found