# -*- tcl -*-
#
# fmt.html
#
# Copyright (c) 2001-2019 Andreas Kupries
#
# Definitions to convert a tcl based manpage definition into
# a manpage based upon HTML markup.
#
################################################################
################################################################
dt_source _common.tcl ; # Shared code
dt_source _html.tcl ; # HTML basic formatting
dt_source _xref.tcl ; # xref management
global _in_example
set _in_example 0
proc c_copyrightsymbol {} {return "[markup "&"]copy;"}
proc bgcolor {} {return ""}
proc border {} {return 0}
proc Year {} {clock format [clock seconds] -format %Y}
c_holdBuffers require synopsis
################################################################
## Backend for HTML markup
# --------------------------------------------------------------
# Handling of lists. Simplified, the global check of nesting and
# legality of list commands allows us to throw away most of the
# existing checks.
global liststack ; # stack of list tags to use in list_end
set liststack {}
proc lpush {t class} {
global liststack
lappend liststack [list [tag/ $t] [litc_getandclear]]
return [taga $t [list class $class]]
}
proc lpop {} {
global liststack
set t [lindex $liststack end]
set liststack [lreplace $liststack end end]
foreach {t l} $t break
litc_set $l
return $t
}
proc fmt_plain_text {text} {
global _in_example
if {$_in_example} {
set text [string map [list \\\\\n \\\n] $text]
}
return $text
}
################################################################
# Formatting commands.
c_pass 1 fmt_manpage_begin {title section version} {c_cinit ; c_clrSections ; return}
c_pass 2 fmt_manpage_begin {title section version} {
global sec_is_open ; set sec_is_open 0
global subsec_is_open ; set subsec_is_open 0
global prev_litem_close ; set prev_litem_close {}
global para_is_open ; set para_is_open 0
global liststack ; set liststack {}
global defaultstyle
XrefInit
c_cinit
set module [dt_module]
set shortdesc [c_get_module]
set description [c_get_title]
set copyright [c_get_copyright]
set pagetitle "$title - $shortdesc"
set hdr ""
if {![Get raw]} {
append hdr [markup {}]
append hdr [tag html] [tag head] \n
append hdr [tag_ title $pagetitle] \n
if {![Extend hdr ByParameter meta]} {
# Insert standard CSS definitions.
append hdr [tag_ style \
"[markup <]!--${defaultstyle}--[markup >]" \
type text/css] \n
}
append hdr [tag/ head] \n
append hdr [ht_comment [c_provenance]]\n
if {$copyright != {}} {
append hdr [ht_comment $copyright]\n
}
append hdr [ht_comment "$title.$section"]
append hdr \n\n
append hdr [tag body]
}
Extend hdr ByParameter header \
@TITLE@ $pagetitle
append hdr [tag* div class doctools] \n
set thetitle "[string trimleft $title :]($section) $version $module \"$shortdesc\""
append hdr [tag_ h1 $thetitle class doctools_title] \n
append hdr [fmt_section Name name] \n
append hdr "[para_open] $title - $description"
return $hdr
}
c_pass 1 fmt_moddesc {desc} {c_set_module $desc}
c_pass 2 fmt_moddesc {desc} NOP
c_pass 1 fmt_titledesc {desc} {c_set_title $desc}
c_pass 2 fmt_titledesc {desc} NOP
c_pass 1 fmt_copyright {desc} {c_set_copyright $desc}
c_pass 2 fmt_copyright {desc} NOP
c_pass 1 fmt_manpage_end {} {c_creset ; return}
c_pass 2 fmt_manpage_end {} {
c_creset
set res ""
set sa [c_xref_seealso]
set kw [c_xref_keywords]
set ca [c_xref_category]
set ct [c_get_copyright]
if {[llength $sa] > 0} {
append res [fmt_section {See Also} see-also] \n
append res [join [XrefList [lsort $sa] sa] ", "] \n
}
if {[llength $kw] > 0} {
append res [fmt_section Keywords keywords] \n
append res [join [XrefList [lsort $kw] kw] ", "] \n
}
if {$ca ne ""} {
append res [fmt_section Category category] \n
append res $ca \n
}
if {$ct != {}} {
append res [fmt_section Copyright copyright] \n
append res [join [split $ct \n] [tag br]\n] [tag br]\n
}
# Close last paragraph, subsection, and section.
append res [para_close][subsec_close][sec_close]
Extend res ByParameter footer
append res [tag/ div]
if {![Get raw]} {
append res [tag/ body] [tag/ html]
}
return $res
}
c_pass 1 fmt_section {name id} {c_newSection $name 1 end $id}
c_pass 2 fmt_section {name id} {
return "[sec_open $id][tag_ h2 [anchor $id $name]]\n[para_open]"
}
c_pass 1 fmt_subsection {name id} {c_newSection $name 2 end $id}
c_pass 2 fmt_subsection {name id} {
return "[subsec_open $id][tag_ h3 [anchor $id $name]]\n[para_open]"
}
# Para breaks inside and outside of lists are identical
proc fmt_nl {} {para_open}
proc fmt_para {} {para_open}
c_pass 2 fmt_require {pkg {version {}}} NOP
c_pass 1 fmt_require {pkg {version {}}} {
if {$version != {}} { append pkg " " $version }
c_hold require [tag_ li "package require [bold $pkg pkgname]"]
return
}
c_pass 2 fmt_usage {cmd args} NOP
c_pass 1 fmt_usage {cmd args} {
if {[llength $args]} {
set text "$cmd [join $args " "]"
} else {
set text $cmd
}
c_hold synopsis [tag_ li $text]
return
}
c_pass 1 fmt_call {cmd args} {
if {[llength $args]} {
set text "$cmd [join $args " "]"
} else {
set text $cmd
}
c_hold synopsis [tag_ li [link $text "#[c_cnext]"]]
return
}
c_pass 2 fmt_call {cmd args} {
if {[llength $args]} {
set text "$cmd [join $args " "]"
} else {
set text $cmd
}
return [fmt_lst_item [anchor [c_cnext] $text]]
}
c_pass 1 fmt_description {did} NOP
c_pass 2 fmt_description {did} {
set result ""
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 $did
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}
set sections [c_sections]
# Pass 2: Generate the markup for the TOC, indenting the
# links according to the level of each section.
append result [fmt_section {Table Of Contents} toc] [para_close] \n
append result [taga ul {class doctools_toc}] \n
set lastlevel 1
set close 0
foreach {name id level} $sections {
# level in {1,2}, 1 = section, 2 = subsection
if {$level == $lastlevel} {
# Close previous item.
if {$close} { append result [tag/ li] \n }
} elseif {$level > $lastlevel} {
# Start list of subsections
append result \n [tag ul] \n
} else { # level < lastlevel
# End list of subsections, and of previous item (two
# actually, the subsection, and the section item).
append result [tag/ li] \n [tag/ ul] \n [tag/ li] \n
}
# Start entry
if {$level == 1} {
append result [taga li {class doctools_section}]
} else {
append result [taga li {class doctools_subsection}]
}
append result [link $name "#$id"]
set close 1
set lastlevel $level
}
if {$lastlevel > 1 } { append result [tag/ ul] \n }
if {$close} { append result [tag/ li] \n }
append result [tag/ ul] \n
# 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 != {}} {
append result [fmt_section Synopsis synopsis] [para_close] [taga div {class doctools_synopsis}] \n
if {$req != {}} {
append result [tag_ ul \n$req\n class doctools_requirements] \n
}
if {$syn != {}} {
append result [tag_ ul \n$syn\n class doctools_syntax] \n
}
append result [tag/ div] \n
}
append result [fmt_section Description $did] \n
return $result
}
################################################################
proc fmt_list_begin {what {hint {}}} {
# NOTE: The hint is ignored. Use stylesheet definitions to modify
# item and general list spacing.
switch -exact -- $what {
enumerated {set tag ol}
itemized {set tag ul}
arguments -
commands -
options -
tkoptions -
definitions {set tag dl}
}
return [para_close][lpush $tag doctools_$what]
}
proc fmt_list_end {} {
set res [para_close][litc_getandclear]\n[lpop][para_open]
return $res
}
proc fmt_lst_item {text} {
set res [para_close][litc_getandclear]\n[tag_ dt $text]\n[tag dd][para_open]
litc_set [tag/ dd]
return $res
}
proc fmt_bullet {} {
set res [para_close][litc_getandclear]\n[tag li][para_open]
litc_set [tag/ li]
return $res
}
proc fmt_enum {} {
set res [para_close][litc_getandclear]\n[tag li][para_open]
litc_set [tag/ li]
return $res
}
proc fmt_cmd_def {command} {
fmt_lst_item [fmt_cmd $command]
}
proc fmt_arg_def {type name {mode {}}} {
set text ""
append text $type " " [fmt_arg $name]
if {$mode != {}} {
append text " (" $mode ")"
}
fmt_lst_item $text
}
proc fmt_opt_def {name {arg {}}} {
set text [fmt_option $name]
if {$arg != {}} {append text " " $arg}
fmt_lst_item $text
}
proc fmt_tkoption_def {name dbname dbclass} {
set text ""
append text "Command-Line Switch:\t[fmt_option $name][tag br]\n"
append text "Database Name:\t[bold $dbname optdbname][tag br]\n"
append text "Database Class:\t[bold $dbclass optdbclass][tag br]\n"
fmt_lst_item $text
}
################################################################
proc fmt_example_begin {} {
global _in_example ; set _in_example 1
return [para_close]\n[tag* pre class doctools_example]
}
proc fmt_example_end {} {
global _in_example ; set _in_example 0
return [tag/ pre]\n[para_open]
}
proc fmt_example {code} {
return "[fmt_example_begin][fmt_plain_text $code][fmt_example_end]"
}
################################################################
proc fmt_arg {text} { italic $text arg }
proc fmt_cmd {text} { bold [XrefMatch $text sa] cmd }
proc fmt_emph {text} { em $text }
proc fmt_opt {text} { span "?$text?" opt }
proc fmt_comment {text} {ht_comment $text}
proc fmt_sectref {title {id {}}} {
if {$id == {}} { set id [c_sectionId $title] }
if {[c_sectionKnown $id]} {
return [span [link $title "#$id"] sectref]
} else {
return [bold $title sectref]
}
}
proc fmt_syscmd {text} {bold [XrefMatch $text sa] syscmd}
proc fmt_method {text} {bold $text method}
proc fmt_option {text} {bold $text option}
proc fmt_widget {text} {bold $text widget}
proc fmt_fun {text} {bold $text function}
proc fmt_type {text} {bold $text type}
proc fmt_package {text} {bold [XrefMatch $text sa kw] package}
proc fmt_class {text} {bold $text class}
proc fmt_var {text} {bold $text variable}
proc fmt_file {text} {return "\"[bold $text file]\""}
proc fmt_namespace {text} {bold $text namespace}
proc fmt_uri {text {label {}}} {
if {$label == {}} {set label $text}
return [link $label $text]
}
proc fmt_image {text {label {}}} {
# text = symbolic name of the image.
set img [dt_imgdst $text {png gif jpg}]
if {$label eq {}} {
set label $text
}
if {$img ne {}} {
return [imagelink $label [LinkTo $img [LinkHere]]]
}
if {[regexp -- {^http://} $text] ||
[regexp -- {^ftp://} $text]} {
return [imagelink $label $text]
}
#puts_stderr here:\t[LinkHere]
#puts_stderr dest:\t$img
#puts_stderr rela:\t[LinkTo $img [LinkHere]]
#puts_stderr
return [strong "Image: $label"]
}
proc fmt_term {text} {italic [XrefMatch $text kw sa] term}
proc fmt_const {text} {bold $text const}
proc fmt_mdash {} { return "[markup &]mdash;" }
proc fmt_ndash {} { return "[markup &]ndash;" }
################################################################
global sec_is_open
set sec_is_open 0
proc sec_open {id} {
global sec_is_open
set res [para_close][subsec_close][sec_close][tag* div id $id class doctools_section]
set sec_is_open 1
return $res
}
proc sec_close {} {
global sec_is_open
if {!$sec_is_open} {return ""}
set sec_is_open 0
return [tag/ div]\n
}
################################################################
global subsec_is_open
set subsec_is_open 0
proc subsec_open {id} {
global subsec_is_open
set res [para_close][subsec_close][tag* div id $id class doctools_subsection]
set subsec_is_open 1
return $res
}
proc subsec_close {} {
global subsec_is_open
if {!$subsec_is_open} {return ""}
set subsec_is_open 0
return [tag/ div]\n
}
################################################################
# Piece of html to close the previous list element, if any.
# Saved on the list stack
global prev_litem_close
set prev_litem_close {}
proc litc_getandclear {} {
global prev_litem_close
set res $prev_litem_close
set prev_litem_close {}
return $res
}
proc litc_set {value} {
global prev_litem_close
set prev_litem_close $value
return
}
################################################################
global para_is_open
set para_is_open 0
proc para_open {} {
global para_is_open
set res [para_close][tag p]
set para_is_open 1
return $res
}
proc para_close {} {
global para_is_open
if {!$para_is_open} {return ""}
set para_is_open 0
return [tag/ p]
}
################################################################
proc GetXref {} { Get xref } ;# xref access to engine parameters
global __var
array set __var {
meta {}
header {}
footer {}
xref {}
raw 0
}
proc Get {varname} {global __var ; return $__var($varname)}
proc fmt_listvariables {} {global __var ; return [array names __var]}
proc fmt_varset {varname text} {
global __var
if {![info exists __var($varname)]} {return -code error "Unknown engine variable \"$varname\""}
set __var($varname) $text
return
}
# Engine parameter handling
proc Extend {v _ by args} {
set html [Get $by]
if {$html == {}} { return 0 }
upvar 1 $v text
if {[llength $args]} {
set html [string map $args $html]
}
append text [markup $html] \n
return 1
}
global defaultstyle
set defaultstyle {
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
}
################################################################