h1 - h6 elements show pilcrow and arrow-up at end of line

[DHB]

I noticed this already in many ruby docs published in the web & found it annoying in my own docs.

To reproduce:

$ cat para.rdoc

=== Shows an annoying paragraph & arrow when you hover over me --->

$ rdoc -o doc para.rdoc

Render the produced HTML and hover over the element.

The "hardcoded" paragraph sign and arrow-up sign stem from:

lib/rdoc/markup/to_html.rb:288:      @res << "<span><a href=\"##{label}\">&para;</a>"

and from

lib/rdoc/markup/to_html.rb:289:   @res << " <a href=\"#documentation\">&uarr;</a></span>"

When I removed the above, the generated docs looked OK at a first glance.

Is this eventually just a "leftover" from debugging?

I could not run the test-suite (on windows) because of another not related windows issue with the pathname method used in RDoc.

However, &para is in:

test/test_rdoc_generator_markup.rb:40:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:26:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:34:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:41:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:48:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:55:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:62:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:71:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:350:    links = '<span><a href="#label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:362:    links = '<span><a href="#class-Foo-label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:375:    links = '<span><a href="#method-i-foo-label-Hello">&para;</a> ' +
test/test_rdoc_markup_to_html.rb:407:    assert_equal "\n<h1>Hello<span><a href=\"#label-Hello\">&para;</a> <a href=\"#documentation\">&uarr;</a></span></h1>\n", @to.res.join   

[drbrain]

This is intentional as it allows you to easily bookmark a heading through the pilcrow and jump to the top of the document with the arrow.

[zzak]

We have an option to strip these tags, but it escapes me right now :trollface:

[DHB]

I see. Got it. Makes sense (to some extend at least) :smile:

This is a admittedly a minor little thing and I truly do not want to waste your valuable time, I just figured to post it for consideration before you release 4.2.

The visible pilcrow sign in pages is often seen as a thing that was not truly intended to be seen but this is maybe a matter of personal taste.

To use it as placeholder to help bookmarking the link is not a bad idea as such, however

a) people can easily bookmark the entire page with one click in every browser and they get a meaningful name suggested before they save it.

b) contrary, if people feel they want to bookmark just the link to the element for whatever reason - by hovering over the pilcrow, right-clicking the mouse, etc. (providing they knew this option even existed), what the browser inserts as name is currently just the paragraph sign. Not really meaningful.

c) The arrow sign, well, again, a matter of personal taste, I guess.

However, to provide visual hooks to bookmark or to navigate - the way it is currently implemented - is in IMHO in mildest terms unusual, but I am not an expert on W3C standards and its recommendations or guidelines - I just felt it looks rather ugly.

Convenience vs. Appearance so to speak.

Could you consider to make it an option to produce and show the additional pilcrow & arrow signs in pages and DEFAULT to NOT having it? .. as a feature request? like configuring it via RDOCOPT or something?

All this no big deal, I just wanted to avoid patching every new release again and again to suit my needs.