Tcl Library Source Code

# -*- tcl -*-
# Convert a doctools document into markdown formatted text
#
# Copyright (c) 2019 Andreas Kupries <[email protected]>

# Note: While markdown is a text format its intended target is HTML,
# making its formatting nearer to that with the ability to set anchors
# and refer to them, linkage in general.

# TODO: Table of contents, section linkage
# TODO: Synopsis command linkage
# TODO: package - xref
# TODO: syscmd - xref
# TODO: cmd - xref
# TODO: term -xref
# TODO: see also, keywords - xref

    TD $term $def
    ContextCommit

    ContextPop
    ContextSet $base
    return
}

##
# # ## ### ##### ########
##

c_pass 1 fmt_section {name id} { c_newSection $name 1 end $id }
c_pass 2 fmt_section {name id} {
    CloseParagraph
    Section [SetAnchor $name $id]
    return
}

c_pass 1 fmt_subsection {name id} { c_newSection $name 2 end $id }
c_pass 2 fmt_subsection {name id} {
    CloseParagraph
    Subsection [SetAnchor $name $id]
    return
}

proc fmt_sectref {title {id {}}} {
    if {$id == {}} { set id [c_sectionId $title] }
    if {[c_sectionKnown $id]} {
    	return [ALink "#$id" $title]
    } else {
	return [Strong $title]
    }
}

c_pass 1 fmt_usage {cmd args} {c_hold synopsis "[join [linsert $args 0 $cmd] " "][LB.]"}
c_pass 1 fmt_call  {cmd args} {c_hold synopsis "[join [linsert $args 0 $cmd] " "][LB.]"}
c_pass 1 fmt_require {pkg {version {}}} {
    set result "package require $pkg"
    if {$version != {}} {append result " $version"}
    c_hold require "$result  "

proc fmt_arg     {text} { Em     $text }
proc fmt_cmd     {text} { Strong $text }
proc fmt_method  {text} { Strong $text }
proc fmt_option  {text} { Strong $text }

proc fmt_uri {text {label {}}} {
    if {$label == {}} { set label $text }
    return "\[$label\]($text)"
    ALink $text $label
}

proc fmt_image {text {label {}}} {
    # text = symbolic name of the image.

    # formatting based on the available data ...

	    CloseCurrent
	}
    }

    return $img
}

c_pass 1 fmt_manpage_begin {title section version} NOP
c_pass 2 fmt_manpage_begin {title section version} {
    Off
    set module      [dt_module]
    set shortdesc   [c_get_module]
    set description [c_get_title]

    MDComment  "$title - $shortdesc"
    MDComment  [c_provenance]
    MDComment  "[string trimleft $title :]($section) $version $module \"$shortdesc\""
    MDCDone

    Section NAME
    Text "$title - $description"
    CloseParagraph
    return
}

c_pass 2 fmt_description {id} {
    On
    set syn [c_held synopsis]
    set req [c_held require]

    # Create the TOC.

    # Pass 1: We have a number of special sections which were not
    #         listed explicitly in the document sources. Add them
    #         now. Note the inverse order for the sections added
    #         at the beginning.

    c_newSection Description 1 0 $id
    if {$syn != {} || $req != {}} {c_newSection Synopsis 1 0 synopsis}
    c_newSection {Table Of Contents} 1 0 toc

    if {[llength [c_xref_seealso]]  > 0} {c_newSection {See Also} 1 end see-also}
    if {[llength [c_xref_keywords]] > 0} {c_newSection Keywords   1 end keywords}
    if {[c_xref_category]         ne ""} {c_newSection Category   1 end category}
    if {[c_get_copyright]         != {}} {c_newSection Copyright  1 end copyright}

    # Pass 2: Generate the markup for the TOC, indenting the
    #         links according to the level of each section.

    TOC

    # Implicit sections coming after the TOC (Synopsis, then the
    # description which starts the actual document). The other
    # implicit sections are added at the end of the document and are
    # generated by 'fmt_manpage_end' in the second pass.
    
    if {$syn != {} || $req != {}} {
	Section [SetAnchor SYNOPSIS synopsis]
	if {($req != {}) && ($syn != {})} {
	    Text $req\n\n$syn
	} else {
	    if {$req != {}} {Text $req}
	    if {$syn != {}} {Text $syn}
	}
	CloseParagraph [Verbatim]
    }

    Section [SetAnchor DESCRIPTION description]
    return
}

c_pass 2 fmt_manpage_end {} {
    set sa [c_xref_seealso]
    set kw [c_xref_keywords]
    set ca [c_xref_category]
    set ct [c_get_copyright]

    CloseParagraph
    if {[llength $sa]} { Special {SEE ALSO} see-also  [join [lsort $sa] ", "] }
    if {[llength $kw]} { Special KEYWORDS   keywords  [join [lsort $kw] ", "] }
    if {$ca ne ""}     { Special CATEGORY   category  $ca                     }
    if {$ct != {}}     { Special COPYRIGHT  copyright $ct [Verbatim]          }
    return
}

proc c_get_copyright {} {
    return [join [c_get_copyright_r] [LB]]
}

##
# # ## ### ##### ########
##

proc Special {title id text {p {}}} {
    Section [SetAnchor $title $id]
    Text $text
    CloseParagraph $p
}

proc TOC {} {
    # While we could go through (fmt_list_begin itemized, item ...,
    # fmt_list_end) it looks to be easier to directly emit paragraphs
    # into the display list. No need to track anything. Just map entry
    # level directly to the proper context.
    Section [SetAnchor {Table Of Contents} toc]

    ContextPush
    lappend toc _bogus_
    lappend toc [ContextNew TOC/Section { List! bullet "  - "     "     "     }]
    lappend toc [ContextNew TOC/SubSect { List! bullet "      - " "         " }]
    ContextPop

    foreach {name id level} [c_sections] {
	# level in {1,2}, 1 = section, 2 = subsection
	Text [ALink "#$id" $name]
	CloseParagraph [lindex $toc $level]
    }

return
    return
}

##
# # ## ### ##### ########
return