From de8cb0a1cf06d091dbe586fed85fb1cf904a33ac Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Fri, 28 Sep 2018 12:37:10 -0400 Subject: [PATCH 1/2] Encode non-alphanum chars like %, + in URLs in the docs Use $itemSymOrIDEnc instead of $itemSymOrID in the id and href attr in a tags. Fixes https://github.com/nim-lang/Nim/issues/9097. Thanks to @LemonBoy for helping with this commit. --- Update the tests too -- "nim c -r nimdoc/tester" passes. --- config/nimdoc.cfg | 5 +++-- .../expected/subdir/subdir_b/utils.html | 8 +++++--- nimdoc/testproject/expected/testproject.html | 18 +++++++++++------- 3 files changed, 19 insertions(+), 12 deletions(-) diff --git a/config/nimdoc.cfg b/config/nimdoc.cfg index 96e91283a..960c58c9e 100644 --- a/config/nimdoc.cfg +++ b/config/nimdoc.cfg @@ -38,7 +38,8 @@ doc.section.toc = """ # * $seeSrc: generated HTML from doc.item.seesrc (if some switches are used). doc.item = """ -
$header
+ +
$header
$desc $seeSrc @@ -48,7 +49,7 @@ $seeSrc # Chunk of HTML emitted for each entry in the HTML table of contents. # See doc.item for available substitution variables. doc.item.toc = """ -
  • $name
    • """ diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.html b/nimdoc/testproject/expected/subdir/subdir_b/utils.html index 285d09d5c..d81be8f48 100644 --- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html +++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html @@ -1250,7 +1250,7 @@ function main() {
  • Procs @@ -1265,7 +1265,8 @@ function main() {

    Types

    -
    SomeType = enum
+
+
    SomeType = enum
   enumValueA, enumValueB, enumValueC
    
 
    
 
@@ -1276,7 +1277,8 @@ function main() {
 
    
 
    Procs
    
 
    
-
    proc someType(): SomeType {...}{.raises: [], tags: [].}
    
+
+
    proc someType(): SomeType {...}{.raises: [], tags: [].}
    
 
    
 constructor.
 
diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html
index 064a70011..f1c567627 100644
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -1255,7 +1255,7 @@ function main() {
 
  • 
   Procs
   
@@ -1263,7 +1263,7 @@ function main() {
 
  • 
   Macros
   
@@ -1271,7 +1271,7 @@ function main() {
 
  • 
   Templates
   
@@ -1297,7 +1297,8 @@ function main() {
 
    
 
    Vars
    
 
    
-
    aVariable: array[1, int]
    
+
+
    aVariable: array[1, int]
    
 
    
 
 
@@ -1307,7 +1308,8 @@ function main() {
 
    
 
    Procs
    
 
    
-
    proc bar[T](a, b: T): T
    
+
+
    proc bar[T](a, b: T): T
    
 
    
 
 
@@ -1317,7 +1319,8 @@ function main() {
 
    
 
    Macros
    
 
    
-
    macro bar(): untyped
    
+
+
    macro bar(): untyped
    
 
    
 
 
@@ -1327,7 +1330,8 @@ function main() {
 
    
 
    Templates
    
 
    
-
    template foo(a, b: SomeType)
    
+
+
    template foo(a, b: SomeType)
    
 
    
 This does nothing 
 

From 903886396dce92789cffb42b7e98315d86677d7e Mon Sep 17 00:00:00 2001
From: Kaushal Modi 
Date: Fri, 28 Sep 2018 14:45:06 -0400
Subject: [PATCH 2/2] Don't prevent ',' from getting escaped in theindex.html

- Enable escaping of links in theindex.html
- Fixes https://github.com/nim-lang/Nim/issues/9107.
- Second part of the fix for https://github.com/nim-lang/Nim/issues/9097.
---
 lib/packages/docutils/rstgen.nim          | 10 +++++++---
 lib/pure/uri.nim                          |  1 +
 nimdoc/testproject/expected/theindex.html |  8 ++++----
 3 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/lib/packages/docutils/rstgen.nim b/lib/packages/docutils/rstgen.nim
index 51bb9c757..232da5c93 100644
--- a/lib/packages/docutils/rstgen.nim
+++ b/lib/packages/docutils/rstgen.nim
@@ -424,11 +424,15 @@ proc sortIndex(a: var openArray[IndexEntry]) =
     if h == 1: break
 
 proc escapeLink(s: string): string =
+  ## This proc is mostly copied from uri/encodeUrl except that
+  ## these chars are also left unencoded: '#', '/'.
   result = newStringOfCap(s.len + s.len shr 2)
   for c in items(s):
     case c
-    of 'a'..'z', '_', 'A'..'Z', '0'..'9', '.', '#', ',', '/':
-      result.add c
+    of 'a'..'z', 'A'..'Z', '0'..'9', '-', '.', '_', '~': # same as that in uri/encodeUrl
+      add(result, c)
+    of '#', '/': # example.com/foo/#bar (don't escape the '/' and '#' in such links)
+      add(result, c)
     else:
       add(result, "%")
       add(result, toHex(ord(c), 2))
@@ -444,7 +448,7 @@ proc generateSymbolIndex(symbols: seq[IndexEntry]): string =
     var j = i
     while j < symbols.len and keyword == symbols[j].keyword:
       let
-        url = symbols[j].link #.escapeLink
+        url = symbols[j].link.escapeLink
         text = if symbols[j].linkTitle.len > 0: symbols[j].linkTitle else: url
         desc = if symbols[j].linkDesc.len > 0: symbols[j].linkDesc else: ""
       if desc.len > 0:
diff --git a/lib/pure/uri.nim b/lib/pure/uri.nim
index dd8040928..d296017dd 100644
--- a/lib/pure/uri.nim
+++ b/lib/pure/uri.nim
@@ -60,6 +60,7 @@ proc encodeUrl*(s: string, usePlus=true): string =
   let fromSpace = if usePlus: "+" else: "%20"
   for c in s:
     case c
+    # https://tools.ietf.org/html/rfc3986#section-2.3
     of 'a'..'z', 'A'..'Z', '0'..'9', '-', '.', '_', '~': add(result, c)
     of ' ': add(result, fromSpace)
     else:
diff --git a/nimdoc/testproject/expected/theindex.html b/nimdoc/testproject/expected/theindex.html
index fc5c0e1c5..106a3be1d 100644
--- a/nimdoc/testproject/expected/theindex.html
+++ b/nimdoc/testproject/expected/theindex.html
@@ -1227,9 +1227,9 @@ function main() {
           
    
 
    bar:
      
 
    • testproject: bar[T](a, b: T): T
      • 
+          data-doc-search-tag="testproject: bar[T](a, b: T): T" href="testproject.html#bar%2CT%2CT">testproject: bar[T](a, b: T): T
           
    • testproject: bar(): untyped
      • 
+          data-doc-search-tag="testproject: bar(): untyped" href="testproject.html#bar.m%2C">testproject: bar(): untyped
           
    
 
    enumValueA:
      
 
    
 
    foo:
      
 
    • testproject: foo(a, b: SomeType)
      • 
+          data-doc-search-tag="testproject: foo(a, b: SomeType)" href="testproject.html#foo.t%2CSomeType%2CSomeType">testproject: foo(a, b: SomeType)
           
    
 
    SomeType:
      
 
    
 
    someType:
      
 
    • utils: someType(): SomeType
      • 
+          data-doc-search-tag="utils: someType(): SomeType" href="subdir/subdir_b/utils.html#someType%2C">utils: someType(): SomeType