re: does fireball markdown support anchor links?

2015-07-09 Thread bowerbird via Markdown-Discuss 
aristotle, your mockery entertains me immensely.

-bowerbird

___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-09 Thread Aristotle Pagaltzis 
* Michel Fortin  [2015-07-09 16:20]:
> I'm not providing this function out of the box for a few reasons: 1.
> any specific algorithm to generate the id to is going to make some
> people complain about non-compatibility with another implementation,
> and 2. it's quite hard to come with something that'll work well with
> non-english text.

There’s also another important reason:

Markdown is used for document fragments that get combined into a single
web page, much more often than it is used for standalone, single full
page documents. E.g. the front page of a weblog with excerpts from
multiple articles; comments in a thread on Reddit, or on GitHub; etc.

But anchors must be unique.

The Markdown processor alone does not have enough information and state
to generate sufficiently unique anchors in such an environment. So, if
automatically generated anchors are desired, their derivation *must* be
performed by code from the environment which has sufficient information
to be able to do that.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-09 Thread Aristotle Pagaltzis 
> the thing about "manually specified" anchors is that they will show
> all kinds of idiosyncrasies. so not only are they work to create, but
> they are also inconsistent, thus undependable, meaning you have to
> look at each one to see what it is, so they have almost _no_ redeeming
> qualities at all.

Yeah, totally agreed.

There are so many advantages to the fact that the anchor is dependably
derived from the text of the heading… well, between all the sites that
use the same Markdown processor configured in the same way… anyway, that
complete consistency is very useful.

It means that if you want to link to the heading, then all you have to
do is copy-paste the text of the heading and then manually edit it into
the format that the Markdown processor uses. You don’t need to look up
the anchor to copy-paste it, which would just be dumb.

It’s also a huge help if you want to know where a link goes – you don’t
even need to click the link (who does that anyway?!), you just scroll
through the document from top to bottom while eyeballing the headers and
hey presto: you know *exactly* where it leads.

Furthermore, in the post-Web 2.0 era URIs are only cool if they could
potentially break before you notice that they are trending. So the fact
that links will break if you edit the text of a heading means derived
anchors are make cool URIs. Really cool URIs sometimes.

So it’s easy to show conclusively that derived anchors are perfect in
every way and the absolute idiosyncrasy of manually specified anchors
results in no redeeming qualities for them at all.
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-09 Thread Michel Fortin 
Le 2015-07-09 à 0:30, Alan Hogan  a écrit :
> Furthermore, auto-gen'd headers *will* break when the text of the header is 
> changed, which can be done for any number of innocuous reasons when we would 
> like the link to be preserved. (Cool URIs don’t change, right?)
>  
> For that reason, I have always been a fan of the ID specification syntax that 
> pandoc, PHP Markdown Extra, maruku, kramdown, and a few others support:
>  
>   ## This is a header {#a-header}
>  
> which compiles to:
>  
>   This is a header
>  
> Look at that! Cleaner Markdown *and* cleaner output than inserting your own 
>  tag. And better, more future-proof section IDs than the auto-generated 
> variety.
> 
> Sadly, I never get to use it, due to the regrettable and totally predictable 
> fact that so many Markdown converters ignore it.
>  
> Not to pick on showdown, but look at its output:
> This is a header {#a-header}

Yeah, this is sad.

I'll just point out that PHP Markdown Extra does support automatic generation 
of headers id as long as you provide it with a proper function to generate the 
id from the content of the header. For instance, you can configure the parser 
like this:

$parser->header_id_func = function ($text) {
return preg_replace('/[^a-z0-9]/', '-', strtolower($text));
};

I'm not providing this function out of the box for a few reasons: 1. any 
specific algorithm to generate the id to is going to make some people complain 
about non-compatibility with another implementation, and 2. it's quite hard to 
come with something that'll work well with non-english text.

Just try it with accented characters and non-latin scripts and appreciate the 
nonsense. 
http://johnmacfarlane.net/babelmark2/?normalize=1&text=%23+English%0A%0A%23+Français%0A%0A%23+Español%0A%0A%23+čeština%0A%0A%23+Росси́я%0A%0A%23+日本%0A%0A%23+한국%0A%0A%23+العَرَبِيةُ%E2%80%8E%E2%80%8E%0A%0A%23+עברית

Honestly, I find the {#a-header} approach better.

-- 
Michel Fortin
[email protected]
https://michelf.ca



smime.p7s
Description: S/MIME cryptographic signature
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

re: does fireball markdown support anchor links?

2015-07-09 Thread bowerbird via Markdown-Discuss 
david said:
>   Compare the manually specified
>   https://github.com/plaid/sanctuary#either
>   to the auto-generated
>   https://github.com/plaid/sanctuary#either--a---c---b---c---either-a-b---c

ok, first of all, if you manually specified this anchor:
>   https://github.com/plaid/sanctuary#either
no way ever would i expect it to go to that location.

especially since this link:
>   https://github.com/plaid/sanctuary#Either
goes to another location. (told you about case glitches.)

nope, i would expect your manually-specified link to
go to the location where this link actually goes:
>   https://github.com/plaid/sanctuary#either-type

(ironically, that header actually has a capital letter,
but the anchor is nonetheless in all-lowercase. ha.)

no, the thing about "manually specified" anchors
is that they will show all kinds of idiosyncrasies.
so not only are they work to create, but they are
also inconsistent, thus undependable, meaning
you have to look at each one to see what it is, so
they have almost _no_ redeeming qualities at all.

furthermore, the github methodology must be
doing some kind of javascript-based search
-- which is not a bad idea, as i suggested here:

>   
> https://medium.com/the-bower/lets-please-use-hashtag-terms-to-create-_arbitrary_-deep-links-f9185d5da2f0

(grok that deep-link! hyphens _and_ underbars!
and random crap at the end just to confuse you.)

except whatever github is doing is implemented
very strangely, so is certainly not what i would do.

however...

***

alan said:
>   If I were to pick a preferred format for auto-generated IDs,
>   it would have to be hyphens. Separating words is desirable
>   as it is more readable. And underscores, though not a terrible option,
>   can be obscured by underlines when the entire URL is presented to a user.

i disagree with several of those points.

but, hey, our own personal opinions don't mean jack.

i would gladly accept _any_ method, even if distasteful,
as long as everyone agreed that that's what we're doing.

so what would make a difference is if all the flavors
would converge on a mutual-agreed-upon method.

but...

>   Of course, I've been on this list too long to expect
>   implementations to actually converge on much of anything.

right, that's never gonna happen, i think we all know that.

so, then, what we need is to poll a million users or so, and
see which of the possible solutions they would most prefer,
and then let that vote guide us. but that won't happen either.

so the guiding principle is this:

if it _is_ broke, but you know you can't fix it,
don't waste time and energy by even trying.
don't even discuss it. pretend it doesn't exist.
(that's something all the flavor-makers can do!)

i would suggest we have reached this point.
thank you for your question, original-poster...

-bowerbird

___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-08 Thread Alan Hogan 



On Wed, Jul 8, 2015, at 08:38 PM, David Chambers wrote:
> GitHub's solution isn't ideal, as automatically generated fragment
> identifiers are rather ugly in some cases.

Totally agree, David.

Furthermore, auto-gen'd headers *will* break when the text of the header
is changed, which can be done for any number of innocuous reasons when
we would like the link to be preserved. (Cool URIs don’t change, right?)

For that reason, I have always been a fan of the ID specification
syntax that pandoc, PHP Markdown Extra, maruku, kramdown, and a few
others support:

## This is a header         {#a-header}

which compiles to:

This is a header

Look at that! Cleaner Markdown *and* cleaner output than inserting your
own  tag. And better, more future-proof section IDs than the auto-
generated variety.

Sadly, I never get to use it, due to the regrettable and totally
predictable fact that so many Markdown converters ignore it.

Not to pick on showdown, but look at its output: This is a header {#a-header}

Compare output of my example above on Babelmark2:
http://ajh.us/babelmark2-header-id-syntax

--
  Alan Hogan
[email protected]
 
 
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-08 Thread David Chambers 
GitHub's solution isn't ideal, as automatically generated fragment
identifiers are rather ugly in some cases. Compare the manually specified

https://github.com/plaid/sanctuary#either

to the auto-generated


https://github.com/plaid/sanctuary#either--a---c---b---c---either-a-b---c

for example.

On 8 July 2015 at 19:42, Alan Hogan  wrote:

> One final thought on the topic:
>
> If I were to pick a preferred format for auto-generated IDs, it would
> have to be hyphens. Separating words is desirable as it is more
> readable. And underscores, though not a terrible option, can be obscured
> by underlines when the entire URL is presented to a user.
>
> #section-name-like-this-preferred
>
> Of course, I've been on this list too long to expect implementations to
> actually converge on much of anything.
> ___
> Markdown-Discuss mailing list
> [email protected]
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
>
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-08 Thread Alan Hogan 
One final thought on the topic:

If I were to pick a preferred format for auto-generated IDs, it would
have to be hyphens. Separating words is desirable as it is more
readable. And underscores, though not a terrible option, can be obscured
by underlines when the entire URL is presented to a user.

#section-name-like-this-preferred

Of course, I've been on this list too long to expect implementations to
actually converge on much of anything.
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-08 Thread Alan Hogan 
This topic actually just came up at work a few days ago. I had manually
inserted named links, aka anchors, into a README.md file.

In the code review on my check-in, someone suggested I use "the same
format we are already using for the rest of the headings" for
"consistency."

Puzzled at first, I realized GitHub was automatically generating IDs
(and floating link icons, on render) to enable section links.

(No, this is not part of GFM, Github Flavored Markdown. It seems to be a
subsequent step.)

I went ahead and deleted my ugly manual anchors, because Github *does*
already provide this, and it made the source cleaner.

The downside of this is that now the links I made to various sections
will not work if viewed outside of Github (e.g., if someone edits it
with a preview on the local computer).

As I wrote  at work --

Generating section links is **not** part of Markdown such as it’s
defined [by Gruber], and various markdown implementations either do it
differently, or not at all.

My Section Name  My Section Name  My Section Name 
My Section Name 

As bowerbird mentioned, there is no consistency (hey, there’s that word
again) in  these auto-generated IDs.

Notably, most implementations do not do it at all (as would be expected,
given that original Markdown does not, either).

See the above example for yourself on Babelmark 2:
http://ajh.us/babelmark2-section-ids

Cheers,

Alan Hogan
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

re: does fireball markdown support anchor links?

2015-07-08 Thread bowerbird via Markdown-Discuss 
david said:
>   an option, though not a pretty one.

it's ugly, yes, but that's not the worst part.

the worst part is that it is a lot of work --
especially if you want a table of contents.

and then it's obstacle-clutter while editing.

it's really something that should be handled
by the converter, not something in the text.

which, by the way, many of the flavors _do_.

but not to the extent that they could or should.

in addition to headers, there should be anchors
at significant places, such as tables and figures.

and again, some flavors do indeed go that far...

however there do remain coordination glitches,
as different flavors create the anchors differently.

some turn spaces to dashes, others to underbars,
and some even delete them entirely, meaning that
they didn't learn that old expertsexchange lesson.

some use camel-case, others go all-lower-case...

some include punctuation as-is, others delete it,
and still others keep anything allowed in filenames
(which varies across platforms, and on the web)...

and of course there's the usual utf-8 complication.

so, as is typical in this coordination-plagued sphere,
users have to actually _look_at_ the anchors to see
what they are, which defeats some of the purpose
of auto-generating them in the first place. oh well...

i'm not even going to suggest that the flavor-makers
try to come to an agreement, because we all know
that they aren't gonna change what they already do...

-bowerbird

p.s.  i guess beamer has an appeal for some people,
but reveal.js is so darn rad, especially its visual editor,
that i would really recommend that you check it out...
there are also other great web-based presentation-tools,
but i can't get at the file with my notes on them right now.

___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-08 Thread David Chambers 
You're quite right, Fletcher. Thank you for correcting me. :)

One thing to keep in mind, Alice, is that Markdown is a superset of HTML,
so one is free to write HTML in cases where there is no Markdown-specific
equivalent. Using  is an option, though not a
pretty one.

On 8 July 2015 at 15:15, Fletcher T. Penney 
wrote:

> Perhaps I misunderstood the original question, but on the chance I was
> correct….
>
>
> I think the problem is not creating the link [link text](#anchor) which is
> standard Markdown, but rather having something to link *to*.
>
>
> For example:
>
> # Heading #
>
> This will create an active link to the [heading](#heading).
>
>
> If this is what you meant, then this was something I added to
> MultiMarkdown and I imagine other implementations have also done similar
> things (and GFM is one of them).  I called them "cross-references", but I'm
> sure others called them different things as well.  In standard Markdown,
> the above link would not work, as there would not be an anchor target named
> "#heading".
>
> 
>
>
> If I'm wrong, and David correctly understood your question then just
> ignore me….  ;)
>
>
> Fletcher
>
>
>
> --
> Fletcher T. Penney
> [email protected]
>
> On Jul 8, 2015, at 5:49 PM, David Chambers  wrote:
>
> Yes. This is a standard part of Markdown.
>
> On 8 July 2015 at 14:21, Alice Williams  wrote:
>
>> Is there a way to get the same HTML anchor links like this:
>>
>> Link text
>>
>> 
>>
>> the gitlab version of markdown supports these links this way:
>>
>> [link text](#anchor)
>>
>> Heading 
>>
>> but this does not work with fireball version of markdown.
>>
>> thanks for any suggestions!
>> Alice
>>
>> ___
>> Markdown-Discuss mailing list
>> [email protected]
>> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
>>
>>
> ___
> Markdown-Discuss mailing list
> [email protected]
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
>
>
>
> ___
> Markdown-Discuss mailing list
> [email protected]
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
>
>
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-08 Thread Fletcher T. Penney 
Perhaps I misunderstood the original question, but on the chance I was correct….


I think the problem is not creating the link [link text](#anchor) which is 
standard Markdown, but rather having something to link *to*.


For example:

# Heading #

This will create an active link to the [heading](#heading).


If this is what you meant, then this was something I added to MultiMarkdown and 
I imagine other implementations have also done similar things (and GFM is one 
of them).  I called them "cross-references", but I'm sure others called them 
different things as well.  In standard Markdown, the above link would not work, 
as there would not be an anchor target named "#heading".




If I'm wrong, and David correctly understood your question then just ignore 
me….  ;)


Fletcher



-- 
Fletcher T. Penney
[email protected] 

On Jul 8, 2015, at 5:49 PM, David Chambers  wrote:

> Yes. This is a standard part of Markdown.
> 
> On 8 July 2015 at 14:21, Alice Williams  wrote:
> Is there a way to get the same HTML anchor links like this:
> 
> Link text
> 
> 
> 
> the gitlab version of markdown supports these links this way:
> 
> [link text](#anchor)
> 
> Heading 
> 
> but this does not work with fireball version of markdown.
> 
> thanks for any suggestions!
> Alice
> 
> ___
> Markdown-Discuss mailing list
> [email protected]
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
> 
> 
> ___
> Markdown-Discuss mailing list
> [email protected]
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: does fireball markdown support anchor links?

2015-07-08 Thread David Chambers 
Yes. This is a standard part of Markdown.

On 8 July 2015 at 14:21, Alice Williams  wrote:

> Is there a way to get the same HTML anchor links like this:
>
> Link text
>
> 
>
> the gitlab version of markdown supports these links this way:
>
> [link text](#anchor)
>
> Heading 
>
> but this does not work with fireball version of markdown.
>
> thanks for any suggestions!
> Alice
>
> ___
> Markdown-Discuss mailing list
> [email protected]
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
>
>
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

does fireball markdown support anchor links?

2015-07-08 Thread Alice Williams 
Is there a way to get the same HTML anchor links like this:

Link text



the gitlab version of markdown supports these links this way:

[link text](#anchor)

Heading 

but this does not work with fireball version of markdown.

thanks for any suggestions!
Alice
___
Markdown-Discuss mailing list
[email protected]
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss