Smalltalk › Pharo › Pharo Smalltalk Users

Pillar automatic anchors

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

Peter Uhnak

Pillar automatic anchors

Hi,

I would like to resolve this issue:

Automatic section anchors: Each section title should automatically generate an implicit hyperlink target (aka, anchor) pointing to the section. The text of the hyperlink target (the "reference name") is the same as that of the section title.

however since I'm not familiar with Pillar I don't know how acceptable this solution could be

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PRHTMLWriter>>visitHeader: aHeader

| level |

level := self configuration headingLevelOffset + aHeader level. "h1 to h7 exist."

level := level min: 7 max: 1.

canvas tag

name: 'h' , level asString;

parameterAt: 'id' put: (self createIdForHeader: aHeader); "<<< addition"

with: [

self writeCounterForHeader: aHeader.

super visitHeader: aHeader ].

canvas newLine

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

and

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

createIdForHeader: aHeader

| id |

id := aHeader text.

id := id asLowercase.

"replace banned characters with dashes"

id := '[^0-9a-z\-]' asRegex copy: id replacingMatchesWith: '-'.

"merge multiple dashes"

id := '-{2,}' asRegex copy: id replacingMatchesWith: '-'.

"remove dashes from beginning/end of the id"

id := '^-|-$' asRegex copy: id replacingMatchesWith: ''.

^ id

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Strictly speaking HTML 5 is very permissive with the value of id, but the question is whether we really want to permit everything. E.g. unicode in url is always asking for trouble.

Thanks,

Peter

Damien Cassou-2

Re: Pillar automatic anchors

Hi Peter,

Peter Uhnák <[hidden email]> writes:

> I would like to resolve this issue:
> Automatic section anchors: Each section title should automatically generate
> an implicit hyperlink target (aka, anchor) pointing to the section. The
> text of the hyperlink target (the "reference name") is the same as that of
> the section title.
>
> however since I'm not familiar with Pillar I don't know how acceptable this
> solution could be
>
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> PRHTMLWriter>>visitHeader: aHeader

[...]

I think this solution is not the right one because it only affects
HTML5. I would prefer that the document is changed by adding anchors to
it. Then, the HTML backend will print these anchors the same way it
prints the existing ones. The transformer infrastructure is made for
that, please use it.

--
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

Peter Uhnak

Re: Pillar automatic anchors

On Fri, Jul 31, 2015 at 10:20 PM, Damien Cassou <[hidden email]> wrote:

Hi Peter,

Peter Uhnák <[hidden email]> writes:

> I would like to resolve this issue:
> Automatic section anchors: Each section title should automatically generate
> an implicit hyperlink target (aka, anchor) pointing to the section. The
> text of the hyperlink target (the "reference name") is the same as that of
> the section title.
>
> however since I'm not familiar with Pillar I don't know how acceptable this
> solution could be
>
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> PRHTMLWriter>>visitHeader: aHeader
[...]

I think this solution is not the right one because it only affects
HTML5. I would prefer that the document is changed by adding anchors to
it.

So in a sense of <a id="whatever" /><hX>..</hX>? And for LaTeX \label{sec:whatever}

(The html form will probably change later to allow clickable headers, but that's another todo, which would probably apply only to HTML)

Then, the HTML backend will print these anchors the same way it
prints the existing ones. The transformer infrastructure is made for
that, please use it.

Thanks for the pointers!

So if I understand it correctly, the Transformer performs sort of post-processing operations on the document tree?

So instead of doing a (semi-)single-pass build of the tree it would be transformed several times?

I'm also assuming this is also used to extend annotations use.

Thanks,

Peter

Damien Cassou-2

Re: Pillar automatic anchors

Peter Uhnák <[hidden email]> writes:

> On Fri, Jul 31, 2015 at 10:20 PM, Damien Cassou <[hidden email]>
> wrote:
>> I think this solution is not the right one because it only affects
>> HTML5. I would prefer that the document is changed by adding anchors to
>> it.
>
> So in a sense of <a id="whatever" /><hX>..</hX>? And for LaTeX
> \label{sec:whatever}

yes

> So if I understand it correctly, the Transformer performs sort of
> post-processing operations on the document tree?

yes

> So instead of doing a (semi-)single-pass build of the tree it would be
> transformed several times? I'm also assuming this is also used to
> extend annotations use.

exactly. There are already many transformers: one to include a pillar
file in another one, one to number lines in scripts, one to number
headers, ...

--
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

CyrilFerlicot

Re: Pillar automatic anchors

In reply to this post by Peter Uhnak

Le 31/07/2015 20:06, Peter Uhnák a écrit :

> Hi,
>
> I would like to resolve this issue:
> Automatic section anchors: Each section title should automatically
> generate an implicit hyperlink target (aka, anchor) pointing to the
> section. The text of the hyperlink target (the "reference name") is the
> same as that of the section title.
>
> however since I'm not familiar with Pillar I don't know how acceptable
> this solution could be
>
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> PRHTMLWriter>>visitHeader: aHeader
> | level |
> level := self configuration headingLevelOffset + aHeader level."h1 to h7
> exist."
> level := level min: 7 max: 1.
> canvas tag
> name: 'h' , level asString;
> parameterAt: 'id' put: (self createIdForHeader: aHeader); "<<< addition"
> with: [
> self writeCounterForHeader: aHeader.
> super visitHeader: aHeader ].
> canvas newLine
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> and
>
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> createIdForHeader: aHeader
> | id |
> id := aHeader text.
> id := id asLowercase.
> "replace banned characters with dashes"
> id := '[^0-9a-z\-]' asRegex copy: id replacingMatchesWith: '-'.
> "merge multiple dashes"
> id := '-{2,}' asRegex copy: id replacingMatchesWith: '-'.
> "remove dashes from beginning/end of the id"
> id := '^-|-$' asRegex copy: id replacingMatchesWith: ''.
> ^ id
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> Strictly speaking HTML 5 is very permissive with the value of id, but
> the question is whether we really want to permit everything. E.g.
> unicode in url is always asking for trouble.
>
> Thanks,
> Peter
>
>

Hi Petter!

I begun a transformer some time ago. His name is "PRAnchorOfSection"
that inherit from "PRNodeTransformer".
For now this transformer is not enable because we need to check some
problems.
For example this works bad if we put a link inside the title. Or what do
we do if we have two times the same title? As "Introduction"?

Cyril

signature.asc (836 bytes) Download Attachment

Peter Uhnak

Re: Pillar automatic anchors

Hi Petter!

I begun a transformer some time ago. His name is "PRAnchorOfSection"
that inherit from "PRNodeTransformer".
For now this transformer is not enable because we need to check some
problems.

Yeah, I started studying this.

For example this works bad if we put a link inside the title.

Maybe combination of using ==PRHeader text== (instead of ==PRHeader children first text== which doesn't work when there's formatting involved... like ! ==PRTransformer==)

and then id filtering could solve this? It will be messy, but not if we also give user the ability to specify anchors explicitly... see further down.

But I see a different problem which I don't think can be solved with generic Transformer...

And that is that in HTML it is customary to place anchor ABOVE or before the target, so when you click on a link it it will show also the name of the chapter, so the user knows where he is.

While in LaTeX it's usually placed underneath. So this would require having an extra HTML-only specific transformer (or something) that would swap them.

Or what do
we do if we have two times the same title? As "Introduction"?

Well ideally user would still be able to specify an explicit anchor, in which case the default one is not generated. So by default it can append a number or something, but user could override it.

I think there's a lot to be learned from Sphinx.

Peter