Tcl Library Source Code

Check-in [0f2ecff317]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Started generation of markdown: docidx.
Timelines: family | ancestors | descendants | both | doc-fixup-and-markdown
Files: files | file ages | folders
SHA3-256:0f2ecff3171a6ce9ea9f6117c01783d126a6a7ca9d3d94d88b53073f3f9a209b
User & Date: aku 2019-03-15 06:28:37
Context
2019-03-18
19:57
Continued generation of markdown: doctoc. check-in: 61b61eed41 user: aku tags: doc-fixup-and-markdown
2019-03-15
06:28
Started generation of markdown: docidx. check-in: 0f2ecff317 user: aku tags: doc-fixup-and-markdown
2019-03-14
19:35
Shuffled the test support files for doctools around for a nicer hierarchy, with fmt, idx, and toc properly segregated. Updated the test suite to match the changes. Furthermore dropped superfluous checks for long-gone `CVS` directories. check-in: 7e7f01191f user: aku tags: doc-fixup-and-markdown
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to modules/doctools/docidx.test.

   308    308   
   309    309   
   310    310   # -------------------------------------------------------------------------
   311    311   ## Series of tests for all available backends, check their formatting.
   312    312   
   313    313   set k 11
   314    314   foreach format {
   315         -    html nroff text
   316         -    wiki null
          315  +    null html nroff
          316  +    text wiki markdown
   317    317   } {
   318    318       set n 0
   319    319       foreach src [TestFilesGlob tests/idx/idx/*] {
   320    320   	# Get the expected result
   321    321   	set dst [localPath [file join tests idx $format [file tail $src]]]
   322    322   	set map {} ; lappend map @USR@ $tcl_platform(user)
   323    323   	set rem {} ; lappend rem $tcl_platform(user) @USR@

Added modules/doctools/mpformats/_markdown.tcl.

            1  +# -*- tcl -*-
            2  +#
            3  +# -- Core support for markdown
            4  +#
            5  +# Copyright (c) 2019 Andreas Kupries <andreas_kupries@sourceforge.net>
            6  +# Freely redistributable.
            7  +
            8  +################################################################
            9  +
           10  +# # ## ### ##### ########
           11  +## `markdown` formatting
           12  +
           13  +proc SectTitle {lb title} {
           14  +    upvar 1 $lb lines
           15  +    lappend lines "# $title"
           16  +    return
           17  +}
           18  +
           19  +proc SubsectTitle {lb title} {
           20  +    upvar 1 $lb lines
           21  +    lappend lines "## $title"
           22  +    return
           23  +}
           24  +
           25  +proc Sub3Title {lb title} {
           26  +    upvar 1 $lb lines
           27  +    lappend lines "### $title"
           28  +    return
           29  +}
           30  +
           31  +proc Sub4Title {lb title} {
           32  +    upvar 1 $lb lines
           33  +    lappend lines "#### $title"
           34  +    return
           35  +}
           36  +
           37  +proc Strong {text} { return __${text}__ }
           38  +proc Em     {text} { return *${text}* }

Added modules/doctools/mpformats/idx.markdown.

            1  +# -*- tcl -*-
            2  +# Engine to convert a docidx document into markdown text.
            3  +#
            4  +# Copyright (c) 2019 Andreas Kupries <andreas_kupries@sourceforge.net>
            5  +# Freely redistributable.
            6  +#
            7  +######################################################################
            8  +
            9  +dt_source _idx_common.tcl
           10  +dt_source _text.tcl
           11  +dt_source _markdown.tcl
           12  +
           13  +proc c_copyrightsymbol {} {return "(c)"}
           14  +
           15  +######################################################################
           16  +# Conversion specification.
           17  +# One-pass processing.
           18  +
           19  +rename idx_postprocess {}
           20  +rename text_postprocess idx_postprocess
           21  +proc   fmt_plain_text {text} {return {}}
           22  +
           23  +################################################################
           24  +## Backend for plain text markup
           25  +
           26  +proc fmt_index_begin {label title} {
           27  +    if {($label != {}) && ($title != {})} {
           28  +	set title "$label -- $title"
           29  +    } elseif {$label != {}} {
           30  +	set title $label
           31  +    } elseif {$title != {}} {
           32  +	 # title is set
           33  +    }
           34  +
           35  +    TextInitialize
           36  +
           37  +    Text "\[//\]: # (Index [Provenance])"
           38  +    CloseParagraph [Verbatim]
           39  +
           40  +    SectTitle hdr $title
           41  +    Text [Compose hdr]
           42  +    CloseParagraph [Verbatim]
           43  +    return
           44  +}
           45  +
           46  +proc fmt_index_end {} {
           47  +    LoadKwid
           48  +    NavBar
           49  +    Keys
           50  +    return
           51  +    
           52  +    set rmargin [RMargin $max]
           53  +
           54  +    incr max
           55  +    set blank [Blank $max] ;# indent
           56  +
           57  +    foreach key [lsort [array names map]] {
           58  +	set keys [join $map($key) ", "]
           59  +	Text [InFlow $keys $rmargin [ReHead $blank $key] $blank]
           60  +	CloseParagraph [Verbatim]
           61  +    }
           62  +    return
           63  +}
           64  +
           65  +proc fmt_key {text} {
           66  +    global key lk ch
           67  +    set lk $text
           68  +    set key($lk) {}
           69  +    set ch([F $lk]) .
           70  +    return
           71  +}
           72  +
           73  +proc fmt_manpage {f l} {Ref [dt_fmap $f] $l}
           74  +proc fmt_url     {u l} {Ref $u           $l}
           75  +proc fmt_comment {text}       {return}
           76  +
           77  +# ### ### ### ######### ######### #########
           78  +
           79  +proc NavBar {} {
           80  +    global ch dot
           81  +    if {![array size ch]} return
           82  +    
           83  +    set nav {}
           84  +    foreach c [lsort -dict [array names ch]] {
           85  +	set ref c[F $c]
           86  +	set ch($c) $ref
           87  +	lappend nav [ALink #$ref $c]
           88  +    }
           89  +
           90  +    Separator
           91  +    
           92  +    Text [join $nav $dot]
           93  +    CloseParagraph [Verbatim]
           94  +
           95  +    Separator
           96  +    return
           97  +}
           98  +
           99  +proc Keys {} {
          100  +    global key
          101  +    set lc {}
          102  +    set kwlist {}
          103  +
          104  +    # For a good display we sort keywords in dictionary order.
          105  +    # We ignore their leading non-alphanumeric characters.
          106  +    set kwlist {}
          107  +    foreach kw [array names key] {
          108  +       set kwx [string trim [regsub -all {^[^a-zA-Z0-9]+} $kw {}]]
          109  +       lappend kwlist [list $kwx $kw]
          110  +    }
          111  +    foreach item [lsort -index 0 -dict $kwlist] {
          112  +       foreach {_ k} $item break
          113  +	set c [F $k]
          114  +	if {$lc != $c} {
          115  +	    CloseParagraph [Verbatim]
          116  +	    Section $c ; set lc $c
          117  +	}
          118  +	BeginKey   $k
          119  +	References $k
          120  +	EndKey
          121  +    }
          122  +
          123  +    CloseParagraph [Verbatim]
          124  +    return
          125  +
          126  +}
          127  +
          128  +proc Section {c} {
          129  +    global ch
          130  +    Text "#### [SetAnchor "Keywords: $c" $ch($c)]"
          131  +    CloseParagraph [Verbatim]
          132  +
          133  +    Text "|||\n"
          134  +    Text "|---|---|\n"
          135  +    return
          136  +}
          137  +
          138  +proc BeginKey {k} {
          139  +    Text "|[SetAnchor $k]|"
          140  +}
          141  +
          142  +proc References {k} {
          143  +    global key dot
          144  +    set refs {}
          145  +    foreach {ref label} $key($k) {
          146  +	lappend refs [SetAnchor $label $ref]
          147  +    }
          148  +    Text [join $refs $dot]
          149  +    return
          150  +}
          151  +
          152  +proc EndKey {} {
          153  +    Text "|\n"
          154  +}
          155  +
          156  +proc Separator {} {
          157  +    Text ----
          158  +    CloseParagraph [Verbatim]
          159  +}
          160  +
          161  +proc ALink {dst label} { return "\[$label]($dst)" }
          162  +
          163  +proc SetAnchor {text {name {}}} {
          164  +    if {$name == {}} { set name [Anchor $text] }
          165  +    return "<a name='$name'></a>$text"
          166  +}
          167  +
          168  +proc Anchor {text} {
          169  +    global kwid
          170  +    if {[info exists kwid($text)]} {
          171  +	return "$kwid($text)"
          172  +    }
          173  +    return [A $text]
          174  +}
          175  +
          176  +proc A {text} {
          177  +    set anchor [regsub -all {[^a-zA-Z0-9]} [string tolower $text] {_}]
          178  +    set anchor [regsub -all {__+} $anchor _]
          179  +    return $anchor
          180  +}
          181  +
          182  +# ### ### ### ######### ######### #########
          183  +## Engine state
          184  +
          185  +proc LoadKwid {} {
          186  +    global kwid
          187  +    # Engine parameter - load predefined keyword anchors.
          188  +    set             ki [Get kwid]
          189  +    if {![llength  $ki]} return
          190  +    array set kwid $ki
          191  +    return
          192  +}
          193  +
          194  +proc Ref {r l} {
          195  +    global  key  lk
          196  +    lappend key($lk) $r $l
          197  +    return
          198  +}
          199  +
          200  +proc F {text} {
          201  +    # Keep only alphanumeric, take first, uppercase
          202  +    # Returns nothing if input has no alphanumeric characters.
          203  +    return [string toupper [string index [regsub -all {[^a-zA-Z0-9]} $text {}] 0]]
          204  +}
          205  +
          206  +# key  : string -> dict(ref -> label) "key formatting"
          207  +# ch   : string -> '.'                "key starting characters"
          208  +# lk   : string                       "last key"
          209  +# kwid : string -> ...
          210  +# even : bool
          211  +
          212  +global key  ; array set key  {}
          213  +global ch   ; array set ch   {}
          214  +global lk   ; set       lk   {}
          215  +global la   ; set       la   {}
          216  +global ti   ; set       ti   {}
          217  +global kwid ; array set kwid {}
          218  +global dot  ; set dot   { &#183; }
          219  +
          220  +# ### ### ### ######### ######### #########
          221  +## Engine parameters
          222  +
          223  +global    __var
          224  +array set __var {
          225  +    kwid {}
          226  +}
          227  +proc Get               {varname}      {global __var ; return $__var($varname)}
          228  +proc idx_listvariables {}             {global __var ; return [array names __var]}
          229  +proc idx_varset        {varname text} {
          230  +    global __var
          231  +    if {![info exists __var($varname)]} {
          232  +	return -code error "Unknown engine variable \"$varname\""
          233  +    }
          234  +    set __var($varname) $text
          235  +    return
          236  +}
          237  +
          238  +##
          239  +# ### ### ### ######### ######### #########

Added modules/doctools/tests/idx/markdown/00.

            1  +
            2  +[//]: # (Index generated by tcllib/doctools/idx with format 'markdown')
            3  +
            4  +# KWIC -- Test

Added modules/doctools/tests/idx/markdown/01.

            1  +
            2  +[//]: # (Index generated by tcllib/doctools/idx with format 'markdown')
            3  +
            4  +# KWIC -- Test
            5  +
            6  +----
            7  +
            8  +[L](#cL)
            9  +
           10  +----
           11  +
           12  +#### <a name='cL'></a>Keywords: L
           13  +
           14  +|||
           15  +|---|---|
           16  +|<a name='lorem'></a>lorem|<a name='ipsum'></a>dolores|

Added modules/doctools/tests/idx/markdown/02.

            1  +
            2  +[//]: # (Index generated by tcllib/doctools/idx with format 'markdown')
            3  +
            4  +# KWIC -- Test
            5  +
            6  +----
            7  +
            8  +[D](#cD) &#183; [L](#cL)
            9  +
           10  +----
           11  +
           12  +#### <a name='cD'></a>Keywords: D
           13  +
           14  +|||
           15  +|---|---|
           16  +|<a name='dolores'></a>dolores|<a name='lorem'></a>ipsum &#183; <a name='dolores'></a>lorem &#183; <a name='ipsum'></a>dolores|
           17  +
           18  +
           19  +#### <a name='cL'></a>Keywords: L
           20  +
           21  +|||
           22  +|---|---|
           23  +|<a name='lorem'></a>lorem|<a name='ipsum'></a>dolores &#183; <a name='lorem'></a>ipsum|