1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748
|
##########################################################################
# TEPAM - Tcl's Enhanced Procedure and Argument Manager
##########################################################################
# tepam_doc.tcl - TEPAM doc generation package
#
# Copyright (C) 2013 Andreas Drollinger
#
# Id: tepam_doc.tcl
##########################################################################
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
##########################################################################
package require Tcl 8.5 9
package require tepam 0.5
namespace eval tepam::doc_gen {
# Exports the major commands from this package:
namespace export doc_gen
# Format validation command (checks if a format is defined)
proc ::tepam::Validate(tepam_doc_format) {v} {expr {[info proc ::tepam::doc_gen::gen($v,Begin)]!=""}}
# get_full_proc_name returns the full qualified procedure name. It takes also into acocunt
# sub-procedure names: 'display message' -> '::display message'
#
proc get_full_proc_name {name} {
return [concat [namespace origin [lindex $name 0]] [lrange $name 1 end]]
}
##########################################################################
# generate: Generates the documentation for a procedure in a certain format
##########################################################################
# The command 'generate' is the main procedure of the document generation framework. It
# calls a set of sub procedures to generate the different document sections. The exact
# content of each document segment is specified for each supported document format in
# a later part of this file.
#
tepam::procedure generate {
-named_arguments_first 1
-short_description "Get procedure documentation"
-description
"Generates the documentation for a given procedure in one of the supported\
formats (TXT, HTML, POD (Perl Doc), DT (TclLib DocTool), or in an application specific\
format).
If a file is provided a full document file is generated that includes a proper file\
header and file footer, and the file name is returned. Header and footer are otherwise\
not generated and the documentation text is returned by doc_gen.
The documentation is by default generated in Tcl style\
(e.g. command <arg1> <arg2> ...). C-style documentation can be generated by setting\
the argument 'style' to 'C' (e.g. command(<arg1>,<arg2>))."
-example "generate -format HTML -dest_file my_func_help.html ::my_func"
-args {
{-format -type tepam_doc_format -default TXT
-description "Documentation format"}
{-style -type string -default Tcl -choices {Tcl C}
-choicelabels {"Tcl style" "C style"}
-description "Procedure calling style used in the generated documentation"}
{-header_footer -type none
-description "If set the header and footer are also generated. This flag is set by default if a file is generated."}
{-dest_file -type file -optional
-description "Destination file name"}
{name -type string -validatecommand {expr ![catch {get_full_proc_name "%P"}]}
-validatecommand_error_text "Unknown procedure provided (argument 'name')"
-description "Procedure name for which the documentation has to be generated"}
}
} {
# Create the full qualified procedure name (procedure name including namespace).
# Check if the procedure name contains already the name space identification:
set ProcName [get_full_proc_name $name]; # Variable name required by 'tepam::PureProcName'
# Set the doc style to 'Tcl' if the short description starts with 'Property:'
if {[info exists ::tepam::ProcDef($ProcName,-short_description)] &&
[string first "Property:" $::tepam::ProcDef($ProcName,-short_description)]==0} {
set style "Tcl"
}
# Define a function indicator for 'C' style documentation
set FuncIndicator [expr {$style=="Tcl" ? "" : "()"}]
# Set the header/footer generation flag if a file is generated
if {[info exists dest_file]} {
set header_footer 1
}
# Create the list of the main and sub-procedure names. Don't consider
# the main procedure that is only used to access the sub procedures
foreach pName [lsort [concat [list $ProcName] [info procs "$ProcName *"]]] {
if {[info exists ::tepam::ProcDef($pName,VarList)]} { # Check that the procedure has been declared as TEPAM procedure
lappend ProcNames $pName
}
}
# Initiate the documentation string variable
set Doc ""
# Genrate the header if required
if {$header_footer} {
append Doc [gen($format,Header) [::tepam::PureProcName]]
}
# Generate the document prolog (preamble)
append Doc [gen($format,Begin)]
### Name section ###
# Add only the short description of the main procedure (in case sub procedures exist)
append Doc [gen($format,SectionTitle) "Name"]
if {[info exists ::tepam::ProcDef($ProcName,-short_description)]} { # Add the short description if existing
append Doc [gen($format,Name) "[::tepam::PureProcName]$FuncIndicator - $::tepam::ProcDef($ProcName,-short_description)"]
} else {
append Doc [gen($format,Name) "[::tepam::PureProcName]$FuncIndicator"]
}
### Synopsis section ###
append Doc [gen($format,SectionTitle) "Synopsis"]
set NbrDescriptions 0
set NbrExamples 0
# Add the synopsis for each main and sub procedures and register if they have a
# description or an example
foreach ProcName $ProcNames {
incr NbrDescriptions [info exists ::tepam::ProcDef($ProcName,-description)]
incr NbrExamples [info exists ::tepam::ProcDef($ProcName,-example)]
append Doc [doc_gen_Synopsis $ProcName $format $style]
}
### Description ###
# Generate a description title if necessary (if a procedure has a description, or if
# there is a main and sub procedures that are matching
if {$NbrDescriptions>0 || [llength $ProcNames]>1} {
append Doc [gen($format,SectionTitle) "Description"]
}
# Loop over all main and sub procedures
foreach ProcName $ProcNames {
# Add the sub-section title (= procedure name) if multiple procedures are matching
if {[llength $ProcNames]>1} {
append Doc [gen($format,SubSectionTitle) $ProcName]
}
# Add (again) the Synopsis line. Some documentation format require this
# synopsis line inside the description section, because the Synopsis is
# automatically derived (eg Tcl DocTools)
append Doc [doc_gen_Synopsis $ProcName $format $style 1]
# Add the description
if {[info exists ::tepam::ProcDef($ProcName,-description)]} {
append Doc [doc_gen_Description $ProcName $format $style]
}
### Arguments ###
# Add the argument section only if only one procedure is matching. The
# arguments are otherwise listed in the description section.
if {$::tepam::ProcDef($ProcName,VarList)!={}} {
if {[llength $ProcNames]==1} {
append Doc [gen($format,SectionTitle) "Arguments"]
}
append Doc [doc_gen_Arguments $ProcName $format $style]
}
}
### Example ###
# Generate a example section if an example exists
if {$NbrExamples>0} {
append Doc [gen($format,SectionTitle) "Example"]
}
# Add the examples of each main and sub procedure
foreach ProcName $ProcNames {
if {[info exists ::tepam::ProcDef($ProcName,-example)]} {
# Add the synopsis of the procedure that has an example, in case multiple
# procedures are matching
if {[llength $ProcNames]>1} {
# Add the sub-section title if multiple procedures are matching
append Doc [gen($format,SubSectionTitle) $ProcName]
}
# Add the example
append Doc [doc_gen_Example $ProcName $format $style]
}
}
# Generate the document epilog
append Doc [gen($format,End)]
# Genrate the footer if required
if {$header_footer} {
append Doc [gen($format,Footer) ""]
}
# Save the documentation in a file and return the file name if 'dest_file'
# is defined. Return the documentation data otherwise.
if {[info exists dest_file]} {
set f [open $dest_file w]
puts $f $Doc
close $f
return $dest_file
} else {
return $Doc
}
}
# GetCleanText removes white spaces and "'" on the line begins.
#
proc GetCleanText {Text} {
regsub -all {\n[\s\t]+'*} $Text "\n" Text
return $Text
}
# doc_gen_Synopsis generates a formatted synopsis line. This string starts with
# the procedure name, followed by the arguments. The arguments are between
# parenthesis if not Tcl style is selected.
#
proc doc_gen_Synopsis {ProcName format style {DescriptionSynopsis 0}} {
# Start the synopsis with the procedure name, followed with '(' if not Tcl style is selected
set Synopsis [::tepam::PureProcName]
append Synopsis [expr {$style=="Tcl" ? " " : "("}]
# Add all arguments, separate them depending the style
set Sep ""
foreach Var $::tepam::ProcDef($ProcName,VarList) {
append Synopsis $Sep
append Synopsis [gen($format,ArgumentString) \
$Var $::tepam::ProcDef($ProcName,Arg,$Var,-optional) \
$::tepam::ProcDef($ProcName,Arg,$Var,IsNamed) \
$::tepam::ProcDef($ProcName,Arg,$Var,-type)]
set Sep [expr {$style=="Tcl" ? " " : ", "}]
}
# Close the parenthesis if non Tcl style is selected
append Synopsis [expr {$style=="Tcl" ? "" : ")"}]
# Returned the formatted synopsis string
if {$DescriptionSynopsis} {
return [gen($format,DescriptionSynopsis) $Synopsis]
} else {
return [gen($format,Synopsis) $Synopsis]
}
}
# doc_gen_Description generates a formatted documentation section. It recognizes
# paragraphs and unordered lists in the description text and formats them adequately.
#
proc doc_gen_Description {ProcName format style} {
# Get the cleaned-up description string
set Description [GetCleanText $::tepam::ProcDef($ProcName,-description)]
# Loop over every paragraph (parts separated with a newline)
set ParStyle ""; # Stores the current paragraph style
set formattedDescription ""; # Stores the formatted description section
foreach Paragraph [split $Description \n] {
# Remove eventual leading and tailing white spaces
set Paragraph [string trim $Paragraph]
# Handle unordered list items (line that starts with '*').
if {[string index $Paragraph 0]=="*"} {
# Add the list begin code if this is the first list item
if {$ParStyle!="list"} {
append formattedDescription [gen($format,DescriptionListBegin)]
}
# Add the list item (remove the leading '*')
append formattedDescription [gen($format,DescriptionListItem) "[string trim [string range $Paragraph 1 end]]"]
set ParStyle "list"
# Handle non list paragraphs
} else {
# Close an eventually opened unordered list
if {$ParStyle=="list"} {
append formattedDescription [gen($format,DescriptionListEnd)]
}
# Add the paragraph
append formattedDescription [gen($format,Description) $Paragraph]
set ParStyle "par"
}
}
# Close an eventually opened unordered list
if {$ParStyle=="list"} {
append formattedDescription [gen($format,DescriptionListEnd)]
}
# Return the formatted description
return $formattedDescription
}
# doc_gen_Arguments generates the formatted argument section which includes a list of arguments
# together with their descriptions and attributes
#
proc doc_gen_Arguments {ProcName format style} {
# Start the section with the argument list prolog
set formattedArguments [gen($format,ArgumentListBegin)]
# Loop through all arguments
foreach Var $::tepam::ProcDef($ProcName,VarList) {
# Add the argument line
append formattedArguments [gen($format,ArgumentListItem) \
$Var $::tepam::ProcDef($ProcName,Arg,$Var,-optional) \
$::tepam::ProcDef($ProcName,Arg,$Var,IsNamed) \
$::tepam::ProcDef($ProcName,Arg,$Var,-type)]
# Start the argument detail section, and add an eventual existing
# argument description
append formattedArguments [gen($format,ArgumentDetailBegin)]
if {[info exists ::tepam::ProcDef($ProcName,Arg,$Var,-description)] && $::tepam::ProcDef($ProcName,Arg,$Var,-description)!=""} {
append formattedArguments [gen($format,ArgumentDescription) $::tepam::ProcDef($ProcName,Arg,$Var,-description)]
}
# Add the argument type if it is known and if it is not a flag (type=none)
if {[lsearch -exact {"" "none"} $::tepam::ProcDef($ProcName,Arg,$Var,-type)]<0} {
append formattedArguments [gen($format,ArgumentAttribute) "Type: $::tepam::ProcDef($ProcName,Arg,$Var,-type)"]
}
# Add the default value if existing. Put it in double quotes ("") if the
# type is unknown or a string, or if the default value is an empty string
if {[info exists ::tepam::ProcDef($ProcName,Arg,$Var,-default)]} {
if {[lsearch -exact {"" "string"} $::tepam::ProcDef($ProcName,Arg,$Var,-type)]>=0 || $::tepam::ProcDef($ProcName,Arg,$Var,-default)==""} {
append formattedArguments [gen($format,ArgumentAttribute) "Default: \"$::tepam::ProcDef($ProcName,Arg,$Var,-default)\""]
} else {
append formattedArguments [gen($format,ArgumentAttribute) "Default: $::tepam::ProcDef($ProcName,Arg,$Var,-default)"]
}
}
# Add the remaining attributes if they exist
if {$::tepam::ProcDef($ProcName,Arg,$Var,-multiple)} {
append formattedArguments [gen($format,ArgumentAttribute) "Multiple: yes"]
}
if {[info exists ::tepam::ProcDef($ProcName,Arg,$Var,-range)]} {
append formattedArguments [gen($format,ArgumentAttribute) "Range: [lindex $::tepam::ProcDef($ProcName,Arg,$Var,-range) 0]..[lindex $::tepam::ProcDef($ProcName,Arg,$Var,-range) 1]"]
}
if {[info exists ::tepam::ProcDef($ProcName,Arg,$Var,-choices)]} {
append formattedArguments [gen($format,ArgumentAttribute) "Choices: [::tepam::GetChoiceHelpText $ProcName $Var]"]
}
append formattedArguments [gen($format,OptionDetailEnd)]
}
# Add the argument section's epilog, and return the optained formatted section string
append formattedArguments [gen($format,OptionEnd)]
return $formattedArguments
}
# doc_gen_Example generates a formatted example section. It handles every
# example line individually and formats it either as a command line, or as
# a result line.
#
proc doc_gen_Example {ProcName format style} {
# Cleanup the example paragraph
set Example [GetCleanText [string trim $::tepam::ProcDef($ProcName,-example)]]
# Generate the example section prolog
set formattedExample [gen($format,ExampleBegin)]
# Loop through all example lines
foreach line [split $Example \n] {
# Format the line either as an example command, or as a result
if {[string range $line 0 1]=="->"} {
append formattedExample [gen($format,ExampleResultLine) $line]
} else {
append formattedExample [gen($format,ExampleCommandLine) $line]
}
}
# Add the example section's epilog, and return the formatted example section
append formattedExample [gen($format,ExampleEnd)]
return $formattedExample
}
##########################################################################
# patch: Patches an existing documentation by inserting procedure documentations
##########################################################################
# Patches an existing master document by inserting procedure documentations. The
# command calls 'generate' to get the documentation of for the different procedures.
#
tepam::procedure patch {
-named_arguments_first 1
-short_description "Patches an existing master document by inserting procedure documentations"
-description
"Patch inserts procedure documentations into an existing master document at the\
locations indicated by insertion placeholders that are matching the pattern of\
'search_pattern'.
The existing master document is either provided as string argument (src_string)\
or as a file (src_file). The final document is returned by patch if no\
destination file is defined (via 'dest_file'). Otherwise, the document is stored\
in a file, and the number of insertion placeholders that could be handled\
successfully is returned.
Any insertion placeholders of the master document are handled by default. By\
defining the argument 'name' the documentation insertion will be restricted\
to a particular procedure.
Patch handles the documentation in one of the supported\
formats (TXT, HTML, POD (Perl Doc), DT (TclLib DocTool), or in an application\
specific format). The documentation is by default generated in Tcl style\
(e.g. command <arg1> <arg2> ...). C-style documentation can be generated by\
setting the argument 'style' to 'C' (e.g. command(<arg1>,<arg2>))."
-example "patch -format HTML -src_file my_func_help.template -dest_file my_func_help.html"
-args {
{-format -type tepam_doc_format -default TXT
-description "Documentation format"}
{-style -type string -default Tcl -choices {Tcl C}
-choicelabels {"Tcl style" "C style"}
-description "Procedure calling style used in the generated documentation"}
{-search_pattern -type string -default {\{!(.*?)!\}}
-description "Regular expression search pattern"}
{-src_string -type string -optional
-description "Source string"}
{-src_file -type existingfile -optional
-description "Source file name"}
{-dest_file -type file -optional
-description "Destination file name"}
{name -type string -optional -validatecommand {expr ![catch {get_full_proc_name "%P"}]}
-validatecommand_error_text "Unknown procedure provided (argument 'name')"
-description "Procedure name to which the document generation is restricted"}
}
-validatecommand {expr {[info exists src_file]!=[info exists src_string]}}
-validatecommand_error_text "Either src_string or src_file need to be defined!"
} {
# In case a procedure name is provided, make sure it is fully qualified
if {[info exists name]} {
set name [get_full_proc_name $name]
}
# Load the master document data
if {[info exists src_file]} {
set f [open $src_file r]
set Doc [read $f 0x10000000]
close $f
} else {
set Doc $src_string
}
# Get all placeholder locations
set AllMatchPos [regexp -all -indices -inline $search_pattern $Doc]
# Handle all placeholders, starting at the document end. Don't rely on
# 'lreverse' (only available in Tcl8.5)
set NbrInsertion 0
for {set m [expr [llength $AllMatchPos]-1]} {$m>=0} {incr m -2} {
set MatchPos [lindex $AllMatchPos $m-1]
set ProcPos [lindex $AllMatchPos $m-0]
set ProcName [string range $Doc [lindex $ProcPos 0] [lindex $ProcPos 1]]
# Catch any errors: Documentations that cannot be generated for certain procedures
# are simply skipped
catch {
# Make sure a fully qualified procedure name is used
set ProcName [get_full_proc_name $ProcName]
# Skip the procedure if it is not matching with the defined procedure name
if {[info exists name] && $name!=$ProcName} continue
# Replace the placeholder with the procedure documentation
set ProcHelp [tepam::doc_gen::generate -format $format -style $style $ProcName]
set Doc [string replace $Doc [lindex $MatchPos 0] [lindex $MatchPos 1] $ProcHelp]
incr NbrInsertion
}
}
# Save the patched master document in a file if 'dest_file' is defined. Return
# the document data otherwise.
if {[info exists dest_file]} {
set f [open $dest_file w]
puts $f $Doc
close $f
return $NbrInsertion
} else {
return $Doc
}
}
##########################################################################
# Documentation style definitions
##########################################################################
# Various document generation options will be stored in the array variable 'Option'.
variable Option
array set Option {}
###### Text ######
# Text document generation options
set Option(TXT,MaxLineLength) 80; # Specifies the word wrap limit
# TxtFormat formats text in the following way: Tabulator characters are
# replaced by 3 spaces. Lines are reformatted to respect the maximum
# allowed line length. In case a line is wrapped, the leading spaces of the
# first line are added to the begin of the following lines. Multiple lines
# can be provided as text piece and these multiple lines are handled
# independently each to another.
proc TxtFormat {Text} {
variable Option
set FormatedText ""
# Replace tabs through 3 spaces:
regsub -all {\t} $Text " " Text
# Extract the initial spaces of the first line:
regexp {^(\s*)} $Text {} SpaceStart
# Loop through each of the provided help text line:
foreach line [split $Text "\n"] {
# Eliminate leading spaces of the line:
regexp {^\s+'*(.*)$} $line {} line
# Cut the line into segments that doesn't exceed the maximum allowed help line length.
# Add in front of each new line the initial spaces of the first line:
while {$line!=""} {
# Align the leading line spaces to the first line:
set line ${SpaceStart}${line}
#### Next line cutoff position evaluation ####
# Select the next line cut position. The default position is set to the line end:
set LastPos [string length $line]
# Search for the last space inside the line section that is inside the specified
# maximum line length:
if {$LastPos>$Option(TXT,MaxLineLength)} {
set LastPos [string last " " $line $Option(TXT,MaxLineLength)]
}
# If the evaluated line break position is inside the range of the initial line spaces,
# something goes wrong and the line should be broken at another adequate character:
if {$LastPos<=[string length $SpaceStart]-1} {
# Search for other good line break characters (:
set LastPos [lindex [lindex \
[regexp -inline -indices {[^,:\.?\)]+$} \
{ProcDef(::ImportTestPointAssignmentsGeneric,Arg_SectionComment,ColumnSeparation}] 0] 0]
# No line break position could be found:
if {$LastPos=={}} {set LinePos 0}
}
# Break the line simply at the maximum allowed length in case no break position could
# be found:
if {$LastPos<=[string length $SpaceStart]-1} {set LastPos $Option(TXT,MaxLineLength)}
# Add the line segment to the help text:
append FormatedText [string range $line 0 [expr $LastPos-1]]\n
# Eliminate the segment from the actual line:
set line [string range $line [expr $LastPos+1] end]
}
}
return $FormatedText
}
proc gen(TXT,Header) {Text} {return [TxtFormat ""]}
proc gen(TXT,Begin) {} {return [TxtFormat ""]}
proc gen(TXT,End) {} {return [TxtFormat ""]}
proc gen(TXT,SectionTitle) {Text} {return [TxtFormat " [string toupper $Text]\n"]}
proc gen(TXT,SubSectionTitle) {Text} {return [TxtFormat " $Text\n"]}
proc gen(TXT,Name) {Text} {return [TxtFormat " $Text\n"]}
proc gen(TXT,Synopsis) {Text} {return [TxtFormat " $Text\n"]}
proc gen(TXT,Description) {Text} {return [TxtFormat " $Text\n"]}
proc gen(TXT,DescriptionSynopsis) {Text} {return ""}
proc gen(TXT,DescriptionListBegin) {} {return [TxtFormat ""]}
proc gen(TXT,DescriptionListItem) {Text} {return [TxtFormat " * $Text\n"]}
proc gen(TXT,DescriptionListEnd) {} {return [TxtFormat ""]}
proc gen(TXT,ArgumentListBegin) {} {return [TxtFormat ""]}
proc gen(TXT,ArgumentString) {Name IsOptional IsNamed Type} {
if {$IsNamed} {set ArgStr "-$Name"}
if {$Type!="none"} {append ArgStr " <$Name>"}
set ArgStr [string trim $ArgStr]
if {$IsOptional} {set ArgStr "\[$ArgStr\]"}
return $ArgStr
}
proc gen(TXT,ArgumentListItem) {Name IsOptional IsNamed Type} {
return " [gen(TXT,ArgumentString) $Name $IsOptional $IsNamed $Type]\n"
}
proc gen(TXT,ArgumentDetailBegin) {} {return [TxtFormat ""]}
proc gen(TXT,ArgumentDescription) {Text} {return [TxtFormat " $Text\n"]}
proc gen(TXT,ArgumentAttribute) {Text} {return [TxtFormat " $Text\n"]}
proc gen(TXT,OptionDetailEnd) {} {return [TxtFormat ""]}
proc gen(TXT,OptionEnd) {} {return [TxtFormat ""]}
proc gen(TXT,ExampleBegin) {} {return [TxtFormat ""]}
proc gen(TXT,ExampleCommandLine) {Text} {return [TxtFormat " $Text"]}
proc gen(TXT,ExampleResultLine) {Text} {return [TxtFormat " $Text"]}
proc gen(TXT,ExampleEnd) {} {return [TxtFormat ""]}
proc gen(TXT,Footer) {Text} {return [TxtFormat ""]}
###### HTML ######
# HTML document generation options
set Option(HTML,CssFile) "tepam_doc_stylesheet.css"; # Specifies the CSS stylesheet file
proc Htmlformat {Text} {
regsub -all {<} $Text {\<} Text
regsub -all {>} $Text {\>} Text
return $Text
}
proc gen(HTML,Header) {Text} {set s "<html>\n"
append s " <head>\n"
append s " <title>[Htmlformat $Text]</title>\n"
append s " <link rel=\"stylesheet\" href=\"$::tepam::doc_gen::Option(HTML,CssFile)\">\n"
append s " </head>\n"
append s " <body>\n"
append s " <h1 class=\"tepam_page_title\">[Htmlformat $Text]</h1>\n"
return $s }
proc gen(HTML,Begin) {} {return "<div class=\"tepam_command_help\">\n"}
proc gen(HTML,End) {} {return "</div><p></p>\n"}
proc gen(HTML,SectionTitle) {Text} {return " <p class=\"tepam_section_title\">[Htmlformat $Text]</p>\n"}
proc gen(HTML,SubSectionTitle) {Text} {return " <p class=\"tepam_sub_section_title\">[Htmlformat $Text]</p>\n"}
proc gen(HTML,Name) {Text} {return " <p class=\"tepam_name\">[Htmlformat $Text]</p>\n"}
proc gen(HTML,Synopsis) {Text} {return " <p class=\"tepam_synopsis\">$Text</p>\n"}
proc gen(HTML,Description) {Text} {return " <p class=\"tepam_description\">[Htmlformat $Text]</p>\n"}
proc gen(HTML,DescriptionSynopsis) {Text} {return ""}
proc gen(HTML,DescriptionListBegin) {} {return " <ul class=\"tepam_description_list\">\n"}
proc gen(HTML,DescriptionListItem) {Text} {return " <li>[Htmlformat $Text]</li>\n"}
proc gen(HTML,DescriptionListEnd) {} {return " </ul>\n"}
proc gen(HTML,ArgumentListBegin) {} {return " <dl>\n"}
proc gen(HTML,ArgumentString) {Name IsOptional IsNamed Type} {
if {$IsNamed} {set ArgStr "-$Name"}
if {$Type!="none"} {append ArgStr " <$Name>"}
set ArgStr [string trim $ArgStr]
if {$IsOptional} {set ArgStr "\[$ArgStr\]"}
return [Htmlformat $ArgStr]
}
proc gen(HTML,ArgumentListItem) {Name IsOptional IsNamed Type} {
return " <dt class=\"tepam_argument\">[gen(HTML,ArgumentString) $Name $IsOptional $IsNamed $Type]</dt>\n"
}
proc gen(HTML,ArgumentDetailBegin) {} {return " <dd>\n"}
proc gen(HTML,ArgumentDescription) {Text} {return " <p class=\"tepam_argument_description\">[Htmlformat $Text]</p>\n"}
proc gen(HTML,ArgumentAttribute) {Text} {return " <p class=\"tepam_argument_attribute\">[Htmlformat $Text]</p>\n"}
proc gen(HTML,OptionDetailEnd) {} {return " </dd>\n"}
proc gen(HTML,OptionEnd) {} {return " </dl>\n"}
proc gen(HTML,ExampleBegin) {} {return " <pre class=\"tepam_example\">"}
proc gen(HTML,ExampleCommandLine) {Text} {return "<strong>[Htmlformat $Text]</strong>\n"}
proc gen(HTML,ExampleResultLine) {Text} {return "<em>[Htmlformat $Text]</em>\n"}
proc gen(HTML,ExampleEnd) {} {return "</pre>\n"}
proc gen(HTML,Footer) {Text} {return " </body>\n<html>"}
###### POD ######
proc Podformat {Text} {
regsub -all {<} $Text {E<lt>} Text
regsub -all {([^E][^<][^l][^t])>} $Text {\1E<gt>} Text
regsub -all {\|} $Text {E<verbar>} Text
regsub -all {/} $Text {E<sol>} Text
return $Text
}
proc gen(POD,Header) {Text} {return [Podformat ""]}
proc gen(POD,Begin) {} {return ""}
proc gen(POD,End) {} {return ""}
proc gen(POD,SectionTitle) {Text} {return "=head1 [Podformat [string toupper $Text]]\n\n"}
proc gen(POD,SubSectionTitle) {Text} {return "=head2 [Podformat $Text]\n\n"}
proc gen(POD,Name) {Text} {return "B<[Podformat $Text]>\n\n"}
proc gen(POD,Synopsis) {Text} {return "$Text\n\n"}
proc gen(POD,Description) {Text} {return "[Podformat $Text]\n\n"}
proc gen(POD,DescriptionSynopsis) {Text} {return ""}
proc gen(POD,DescriptionListBegin) {} {return "=over 4\n\n"}
proc gen(POD,DescriptionListItem) {Text} {return "=item * [Podformat $Text]\n\n"}
proc gen(POD,DescriptionListEnd) {} {return "=back\n\n"}
proc gen(POD,ArgumentListBegin) {} {return "=over 4\n\n"}
proc gen(POD,ArgumentString) {Name IsOptional IsNamed Type} {
if {$IsNamed} {set ArgStr "-$Name"}
if {$Type!="none"} {append ArgStr " <$Name>"}
set ArgStr [string trim $ArgStr]
if {$IsOptional} {set ArgStr "\[$ArgStr\]"}
return [Podformat $ArgStr]
}
proc gen(POD,ArgumentListItem) {Name IsOptional IsNamed Type} {
return "=item [gen(POD,ArgumentString) $Name $IsOptional $IsNamed $Type]\n\n"
}
proc gen(POD,ArgumentDetailBegin) {} {return ""}
proc gen(POD,ArgumentDescription) {Text} {return "[Podformat $Text]\n\n"}
proc gen(POD,ArgumentAttribute) {Text} {return "[Podformat $Text]\n\n"}
proc gen(POD,OptionDetailEnd) {} {return ""}
proc gen(POD,OptionEnd) {} {return "=back\n\n"}
proc gen(POD,ExampleBegin) {} {return ""}
proc gen(POD,ExampleCommandLine) {Text} {return "C<B<[Podformat $Text]>>\n\n"}
proc gen(POD,ExampleResultLine) {Text} {return "C<I<[Podformat $Text]>>\n\n"}
proc gen(POD,ExampleEnd) {} {return ""}
proc gen(POD,Footer) {Text} {return ""}
###### Tcllib doctools ######
proc Dtformat {Text} {
regsub -all {([\[\]])} $Text {\\\1} Text
return $Text
}
proc gen(DT,Header) {Text} {
upvar ProcName ProcName
set s "\[manpage_begin \"$Text\" n 1.0.3\]\n"
if {[info exists ::tepam::ProcDef($ProcName,-short_description)]} {
append s "\[moddesc \{[Dtformat $::tepam::ProcDef($ProcName,-short_description)]\}\]\n"
append s "\[titledesc \{[Dtformat $::tepam::ProcDef($ProcName,-short_description)]\}\]\n"
}
append s "\[description\]\n"
return $s
}
proc gen(DT,Begin) {} {return ""}
proc gen(DT,End) {} {return ""}
proc gen(DT,SectionTitle) {Text} {
if {[lsearch -exact {Name Synopsis Description} $Text]>=0} return
return "\n\[section \"[Dtformat $Text]\"\]\n\n"
}
proc gen(DT,SubSectionTitle) {Text} {
return "\n\[subsection \"[Dtformat $Text]\"\]\n\n"
}
proc gen(DT,Name) {Text} {return ""}
proc gen(DT,Synopsis) {Text} {return ""}; # DocTools generates automatically the Synopsis
proc gen(DT,Description) {Text} {
return "[Dtformat $Text]\[para\]\n"}
proc gen(DT,DescriptionSynopsis) {Text} { # Add the synopsis to the begin of the description. This will generate then also the Synopsis.
set s "\[list_begin definitions\]\n"
append s "\[call $Text\]\n"
append s "\[list_end\]\n"
return $s
}
proc gen(DT,DescriptionListBegin) {} {return "\[list_begin itemized\]\n"}
proc gen(DT,DescriptionListItem) {Text} {return " \[item\][Dtformat $Text]\n"}
proc gen(DT,DescriptionListEnd) {} {return "\[list_end\]\n"}
proc gen(DT,ArgumentListBegin) {} {return "\[list_begin definitions\]\n\n"}
proc gen(DT,ArgumentString) {Name IsOptional IsNamed Type} {
if {$IsNamed} {set ArgStr "-$Name"}
if {$Type!="none"} {append ArgStr " \[arg $Name\]"}
set ArgStr [string trim $ArgStr]
if {$IsOptional} {set ArgStr "\[opt \"$ArgStr\"\]"}
return $ArgStr
}
proc gen(DT,ArgumentListItem) {Name IsOptional IsNamed Type} {
return "\[def [gen(DT,ArgumentString) $Name $IsOptional $IsNamed $Type]\]\n"
}
proc gen(DT,ArgumentDetailBegin) {} {return ""}
proc gen(DT,ArgumentDescription) {Text} {return " \[para\][Dtformat $Text]\n"}
proc gen(DT,ArgumentAttribute) {Text} {return " \[para\][Dtformat $Text]\n"}
proc gen(DT,OptionDetailEnd) {} {return "\n"}
proc gen(DT,OptionEnd) {} {return "\[list_end\]\n"}
proc gen(DT,ExampleBegin) {} {return "\[para\]\n\[example \{\n"}
proc gen(DT,ExampleCommandLine) {Text} {return "[Dtformat $Text]\n"}
proc gen(DT,ExampleResultLine) {Text} {return "[Dtformat $Text]\n"}
proc gen(DT,ExampleEnd) {} {return "\}\]\n"}
proc gen(DT,Footer) {Text} {return "\[manpage_end\]"}
}; # End namespace tepam::doc
# Specify the TEPAM version that is provided by this file:
package provide tepam::doc_gen 0.1.3
##########################################################################
# Id: tepam_doc.tcl
# Modifications:
#
# Revision 0.1.1 2013/10/18 droll
# * Correction of bug [66d0effebc]: POD format incorrectly formatted
#
# Revision 0.1.0 2013/10/14 droll
# * First TEPAM doc_gen revision
##########################################################################
|