edown mechanically converts external .html links to .md #21

Closed
norton opened this Issue Nov 21, 2012 · 7 comments

Comments

Projects
None yet
2 participants
Contributor

norton commented Nov 21, 2012

I haven't fully traced the details but it seems that edown mechanically converts external .html links to .md links.

Here is an example of incorrect conversion:

  ------
  -<a href="http://ubf.github.com/ubf/ubf-user-guide.en.html">http://ubf.github.com/ubf/ubf-user-guide.en.html</a> for further
  +<a href="http://ubf.github.com/ubf/ubf-user-guide.en.md">http://ubf.github.com/ubf/ubf-user-guide.en.html</a> for further
  ------

The desired behaviour is to only convert links internal to the edocs.

Contributor

uwiger commented Nov 23, 2012

Thanks,

I hope to have time to look into this in the near future. My suspicion, without having looked, is that edoc expands the refererences too early, so that edown cannot tell one kind of link from another.

/Ulf

Sent from my iPad

On 21 nov 2012, at 10:05, Joseph Wayne Norton notifications@github.com wrote:

I haven't fully traced the details but it seems that edown mechanically converts external .html links to .md links.

Here is an example of incorrect conversion:


-http://ubf.github.com/ubf/ubf-user-guide.en.html for further
+http://ubf.github.com/ubf/ubf-user-guide.en.html for further


The desired behaviour is to only convert links internal to the edocs.


Reply to this email directly or view it on GitHub.

Contributor

norton commented Nov 23, 2012

I checked further in detail and it seems this might be an issue with asciiedoc and not edown ... sorry!

Nevertheless, here is how to repeat this behaviour:

  ------
  $ git clone git://github.com/norton/asciiedoc.git
  $ cd ubf
  $ make deps compile doc
  $ git diff
  --- a/README.md
  +++ b/README.md
  @@ -88,7 +88,7 @@ and the backend output markups (which can be almost any type o
   SGML/XML markup) can be customized and extended by the user.</p>
   <p>AsciiDoc is free software and is licenced under the terms of the <em>GNU
   General Public License version 2</em> (GPLv2).</p>
  -<p>See <a href="http://www.methods.co.nz/asciidoc/index.html">http://www.method
  +<p>See <a href="http://www.methods.co.nz/asciidoc/index.md">http://www.method
   ------

The above produces documentation using asciiedoc and edown.

Next, I then tried using just edown by editing the rebar.config.doc file slightly.

------
$ git diff rebar.config.doc
-{edoc_opts, [{doclet, asciiedown_doclet}
+{edoc_opts, [{doclet, edown_doclet}   
$ make doc
$ grep methods README.md 
General Public License version 2' (GPLv2).See http://www.methods.co.nz/asciidoc/index.html for further details.
------

The link looks OK using just edown.

Please feel free to ignore this issue. I'll investigate asciiedoc and edown flow in detail later.

Contributor

uwiger commented Nov 23, 2012

Ok, n.p.

BR,
Ulf

2012/11/23 Joseph Wayne Norton notifications@github.com

I checked further in detail and it seems this might be an issue with
asciiedoc and not edown ... sorry!

Nevertheless, here is how to repeat this behaviour:


$ git clone git://github.com/norton/asciiedoc.git
$ cd ubf
$ make deps compile doc
$ git diff
--- a/README.md
+++ b/README.md
@@ -88,7 +88,7 @@ and the backend output markups (which can be almost any type o
SGML/XML markup) can be customized and extended by the user.

AsciiDoc is free software and is licenced under the terms of the GNU General Public License version 2 (GPLv2).

-

See http://www.method +

See http://www.method


The above produces documentation using asciiedoc and edown.

Next, I then tried using just edown by editing the rebar.config.doc file
slightly.


$ git diff rebar.config.doc
-{edoc_opts, [{doclet, asciiedown_doclet}
+{edoc_opts, [{doclet, edown_doclet}
$ make doc
$ grep methods README.md

General Public License version 2' (GPLv2).See http://www.methods.co.nz/asciidoc/index.html for further details.

The link looks OK using just edown.

Please feel free to ignore this issue. I'll investigate asciiedoc and
edown flow in detail later.


Reply to this email directly or view it on GitHubhttps://github.com/esl/edown/issues/21#issuecomment-10654021.

Contributor

norton commented Nov 23, 2012

I investigated a little further. Using edown standalone (w/o asciiedoc), I created a small counterexample. The wiki notation for external links can illustrate this behaviour. I don't see an obvious fix for this issue.

thanks,
Joe

$ git diff
diff --git a/README.md b/README.md
index d67e456..335c63d 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,10 @@ a markdown-based index and overview. Currently, the
 edoc_doclet creates an index.html and overview.html,
 which do not point to the .md files.

+"[`http://www.w3c.org/.html`](http://www.w3c.org/.md)"
+
+http://www.w3c.org/.html
+
 To generate markdown edoc, run:<pre>
 edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).
 </pre>
diff --git a/doc/README.md b/doc/README.md
index 5a181fc..608bac0 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -17,6 +17,10 @@ a markdown-based index and overview. Currently, the
 edoc_doclet creates an index.html and overview.html,
 which do not point to the .md files.

+"[`http://www.w3c.org/.html`](http://www.w3c.org/.md)"
+
+http://www.w3c.org/.html
+
 To generate markdown edoc, run:<pre>
 edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).
 </pre>
diff --git a/doc/overview.edoc b/doc/overview.edoc
index 69b129f..61b8ee4 100644
--- a/doc/overview.edoc
+++ b/doc/overview.edoc
@@ -12,6 +12,11 @@ a markdown-based index and overview. Currently, the
 edoc_doclet creates an index.html and overview.html,
 which do not point to the .md files.

+
+"[http://www.w3c.org/.html]"
+
+http://www.w3c.org/.html
+
 To generate markdown edoc, run:

 <pre>
Contributor

uwiger commented Nov 23, 2012

In some cases, I have introduced special element tags in edown, so that I can tell in later stages (e.g. the xmerl-to-HTML expansion stage) what kind of text block it is. Perhaps you could add an attribute in the 'a' elements produced by asciiedoc_doclet:parse_xml/2, signaling to edown that the links are to remain as they are?

Contributor

norton commented Nov 23, 2012

Hmm, I have a work-around for this issue.

I have chosen the path of least resistance ... it works but I don't really like it.

norton/asciiedoc@c219ccc

Thanks for your help.

norton closed this Nov 23, 2012

Contributor

norton commented Nov 23, 2012

And thanks for creating "edown" - a very helpful, time saving tool.

@tatsuya6502 tatsuya6502 pushed a commit to hibari/asciiedoc that referenced this issue Apr 4, 2015

@norton norton Prevent edown from converting external .html links to .md links
This is a work-around for edown issue #21
(esl/edown#21).
c219ccc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment