[:for sm [:get_sub_methods] { - [$sm render -initscript [list set supermethod [current]] -template submethod] + [$sm render -initscript [list set supermethod [current]] submethod] }] } - { [:?var :@parameter { Index: library/lib/doc-assets/@project.html.asciidoc =================================================================== diff -u --- library/lib/doc-assets/@project.html.asciidoc (revision 0) +++ library/lib/doc-assets/@project.html.asciidoc (revision d9b47262886ea198bd62861a30a212ab0e31b3bb) @@ -0,0 +1,102 @@ + + + + +
+
+ <stefan.sobernig@wu.ac.at>
<gustaf.neumann@wu.ac.at>
+ [$project version] +
+[:!let tmpls [dict create ::nx::doc::@class class.html.asciidoc ::nx::doc::@package package.html.asciidoc ::nx::doc::@object object.html.asciidoc ::nx::doc::@command command.html.asciidoc]]
+[$project name] API documentation
++ <stefan.sobernig@wu.ac.at>
<gustaf.neumann@wu.ac.at>
+ [$project version] +
+
+Table of Contents
+ [:for feature [dict keys $project_entities] {
+
+ [$feature pretty_plural]
+
+ [:for inst [dict get $project_entities $feature] {
+
+ [$inst name]
+
+ }]
+ }]
+ [:?var :@glossary {
+
+ Glossary
+
+ }]
+
+ [:for feature [dict keys $project_entities] {
+ [:for inst [dict get $project_entities $feature] {
+
+
+
+
Index: library/lib/doc-assets/@project.html.yuidoc
===================================================================
diff -u
--- library/lib/doc-assets/@project.html.yuidoc (revision 0)
+++ library/lib/doc-assets/@project.html.yuidoc (revision d9b47262886ea198bd62861a30a212ab0e31b3bb)
@@ -0,0 +1,16 @@
+
+
+
+
+
+
+ }]
+ }]
+ [:?var :@glossary {
+ [$feature pretty_name] [$inst name]
+
+ [:? {[dict exists $tmpls [$inst info class]]} {
+ [$inst render]
+ }]
+
+
+
+ }]
+Glossary
+
+ [:!let entries [sorted [:@glossary] name]]
+ [:for entry $entries {
+ [:!let ddesc [$entry as_text]]
+ [:?objvar $entry @acronym {
+ [:!let dtext [$entry @acronym]]
+ [:? {$ddesc ne ""} {
+ [:!let ddesc "[$entry @pretty_name] — $ddesc"]
+ } - {
+ [:!let ddesc "[$entry @pretty_name]"]
+ }]
+ } - {
+ [:!let dtext [$entry @pretty_name]]
+ }]
+
+ $dtext
+
+
+
+ }]
+
+ $ddesc
+ [:?objvar $entry refs { + [:? {[$entry eval [concat dict exists \${:refs} [current]]]} { ++ [:!let refs [sort_by_value [$entry eval [concat dict get \${:refs} [current]]]]] + [:for src [dict keys $refs] { + + [$src make_link [current]] + ([dict get $refs $src]) + + }] +
+ }] + }] +
+
+
Index: library/lib/doc-assets/filter.html.yuidoc
===================================================================
diff -u -r8cfd5973ca93d4c014d0a0500bc4151972e1d80a -rd9b47262886ea198bd62861a30a212ab0e31b3bb
--- library/lib/doc-assets/filter.html.yuidoc (.../filter.html.yuidoc) (revision 8cfd5973ca93d4c014d0a0500bc4151972e1d80a)
+++ library/lib/doc-assets/filter.html.yuidoc (.../filter.html.yuidoc) (revision d9b47262886ea198bd62861a30a212ab0e31b3bb)
@@ -1,3 +1,4 @@
+[:!let filter_available 1]
\ No newline at end of file
+
Index: library/lib/doc-assets/leftbar.html.yuidoc
===================================================================
diff -u -r8cfd5973ca93d4c014d0a0500bc4151972e1d80a -rd9b47262886ea198bd62861a30a212ab0e31b3bb
--- library/lib/doc-assets/leftbar.html.yuidoc (.../leftbar.html.yuidoc) (revision 8cfd5973ca93d4c014d0a0500bc4151972e1d80a)
+++ library/lib/doc-assets/leftbar.html.yuidoc (.../leftbar.html.yuidoc) (revision d9b47262886ea198bd62861a30a212ab0e31b3bb)
@@ -10,7 +10,7 @@
[:? {[:info has type [$feature part_class]] && [current] eq $inst} {
[:!let css "selected" ]
}]
- [:? {[dict exists $self_owned_parts $feature]} {
+ [:? {[info exists filter_available] && [dict exists $self_owned_parts $feature]} {
[:! lappend css [expr {[$inst pinfo get -default 0 bundle call-protected]?"protected":""}]]
[:! lappend css [expr {[$inst !get @deprecated]?"deprecated":""}]]
[:! lappend css [$inst statustoken]]
Fisheye: Tag d9b47262886ea198bd62861a30a212ab0e31b3bb refers to a dead (removed) revision in file `library/lib/doc-assets/multifile.html.yuidoc'.
Fisheye: No comparison available. Pass `N' to diff?
Fisheye: Tag d9b47262886ea198bd62861a30a212ab0e31b3bb refers to a dead (removed) revision in file `library/lib/doc-assets/singlefile.html.asciidoc'.
Fisheye: No comparison available. Pass `N' to diff?
Index: library/lib/doc-tools.tcl
===================================================================
diff -u -r8cfd5973ca93d4c014d0a0500bc4151972e1d80a -rd9b47262886ea198bd62861a30a212ab0e31b3bb
--- library/lib/doc-tools.tcl (.../doc-tools.tcl) (revision 8cfd5973ca93d4c014d0a0500bc4151972e1d80a)
+++ library/lib/doc-tools.tcl (.../doc-tools.tcl) (revision d9b47262886ea198bd62861a30a212ab0e31b3bb)
@@ -1412,13 +1412,14 @@
Class create TemplateData {
- :attribute current_template_name
+ #:attribute current_template_name
- :class-object attribute current_format
- :class-object attribute current_theme
- :public forward current_format [current] %method
- :public forward current_theme [current] %method
+ :class-object attribute renderer
+ :public forward renderer [current] %method
+ #:class-object attribute current_theme
+ #:public forward current_theme [current] %method
+
#
# TODO: For now, this acts as the counterweight to "origin",
# when @use aliasing is used, processed_entity can be used to
@@ -1428,84 +1429,33 @@
:class-object attribute rendered_entity:object,type=::nx::doc::Entity
:public forward rendered_entity [current] %method
- :method initialise {with_template_path} {
- :rendered_entity [current]
- :set_template_specifics {*}[split $with_template_path .]
- }
-
- :method set_template_specifics {
- current_template_name:optional
- current_format:optional
- current_theme:optional
- } {
- foreach prop [info vars] {
- if {[info exists $prop] && [set $prop] ne ""} {
- :$prop [set $prop]
- }
- }
- }
-
- :public method read_tmpl {path} {
- if {[file pathtype $path] ne "absolute"} {
- set assetdir [find_asset_path]
- #
- # auto-complete partial template names
- #
- set path_as_list [concat {*}[split $path .]]
- switch -- [llength $path_as_list] {
- 1 {
- lappend path_as_list [:current_format] [:current_theme]
- }
- 2 {
- lappend path_as_list [:current_theme]
- }
- 3 {;}
- default {
- error "Wrong # of components in template name '$path'."
- }
- }
- set tmpl [file join $assetdir [join $path_as_list .]]
- } else {
- set tmpl [file normalize $path]
- }
- if {![[current class] eval [list info exists :templates($tmpl)]]} {
- if {![file exists $tmpl] || ![file isfile $tmpl]} {
- error "The template file '$path' was not found."
- }
- set fh [open $tmpl r]
- [current class] eval [list set :templates($tmpl) [read $fh]]
- catch {close $fh}
- }
-
- return [[current class] eval [list set :templates($tmpl)]]
- }
-
-
:public method render_start {} {;}
:public method render_end {} {;}
-
+
# This mixin class realises a rudimentary templating language to
# be used in nx::doc templates. It realises language expressions
# to verify the existence of variables and simple loop constructs
:public method render {
{-initscript ""}
- {-template:substdefault "[namespace tail [:info class]]"}
- {entity:substdefault "[current]"}
+ -theme
+ {name:substdefault "[namespace tail [:info class]]"}
} {
- $entity initialise $template
+ :rendered_entity [current]
# Here, we assume the -nonleaf mode being active for {{{[eval]}}}.
- set tmplscript [list subst [:read_tmpl $template]]
+ # set tmplscript [list subst [:read_tmpl $template]]
+ set tmplscript [list subst [[:renderer] getTemplate $name \
+ {*}[expr {[info exists theme]?$theme:""}]]]
#
# TODO: This looks awkward, however, till all requirements are
# figured out (as for the origin mechanism) we so keep track
# of the actual rendered entity ... review later ...
#
- $entity render_start
- set content [$entity eval [subst -nocommands {
+ :render_start
+ set content [:eval [subst -nocommands {
$initscript
$tmplscript
}]]
- $entity render_end
+ :render_end
return [string trim $content \n]
}
@@ -1518,12 +1468,12 @@
uplevel 1 [list ::set $var $value]
return
}
-
+
:method ! {cmd args} {
uplevel 1 [list ::$cmd {*}$args]
return
}
-
+
:public method !get {-sortedby -with -where varname} {
set origin [:origin]
if {![$origin eval [list info exists :$varname]]} return
@@ -1532,7 +1482,7 @@
} else {
set r [uplevel 1 [list $origin eval [list ::set :$varname] ]]
}
-
+
if {[info exists where]} {
set l [list]
foreach item $r {
@@ -1542,15 +1492,15 @@
}
set r $l
}
-
+
if {[info exists with]} {
set l [list]
foreach item $r {
lappend l [$item eval [list set :$with]] $item
}
set r $l
}
-
+
return $r
}
@@ -1601,20 +1551,23 @@
}
}
- :method include {{template:substdefault "[namespace tail [:info class]]"}} {
- uplevel 1 [list subst [:read_tmpl $template]]
+ :method include {
+ -theme
+ {name:substdefault "[namespace tail [:info class]]"}
+ } {
+ uplevel 1 [list subst [[:renderer] getTemplate $name \
+ {*}[expr {[info exists theme]?$theme:""}]]]
}
-
+
:method listing {{-inline true} script} {
set iscript [join [list [list set inline $inline] [list set script $script]] \n]
- :render -initscript $iscript -template [current method].[:current_format].[:current_theme]
-
+ :render -initscript $iscript [current method]
}
-
+
:method link args {
error "Subclass responsibility: You must provide a method definition of '[current method]' in a proper subclass"
}
-
+
set :markup_map(sub) {
"'''" "\[:listing \{"
"'''" "\}\]"
@@ -1689,18 +1642,96 @@
}
- #
- # A default TemplateData implementation, targeting the derived YUI
- # Doc templates.
- #
-
+ #
+ # A Renderer base class ...
+ #
Class create Renderer -superclass MixinLayer {
+ :attribute {extension "[namespace tail [current]]"}
+ :attribute extends:object,type=[current]
+
+ #
+ # mixin-layer management
+ #
+
:method init args {
set :prefix "::nx::doc"
next
}
+
+ :public method apply {} {
+ if {[info exists :extends]} {
+ ${:extends} [current method]
+ }
+ next
+ }
+
+ :public method revoke {} {
+ next
+ if {[info exists :extends]} {
+ ${:extends} [current method]
+ }
+ }
+
+ #
+ # template management
+ #
+
+ :attribute current_theme
+ :protected attribute {templates {[dict create]}}
+
+ :public method addTemplate {name theme body} {
+ dict set :templates $theme $name $body
+ return $body
+ }
+ :public method deleteTemplate {name theme} {
+ dict remove ${:templates} $theme $name
+ }
+ :public method getTemplate {
+ name
+ {theme:substdefault "${:current_theme}"}
+ } {
+ if {[dict exists ${:templates} $theme $name]} {
+ return [dict get ${:templates} $theme $name]
+ } else {
+ #
+ # 1) if available, read-in template file lazily
+ #
+ set templateName $name.${:extension}.$theme
+ set body [:readAsset $templateName]
+ if {$body ne ""} {
+ return [:addTemplate $name $theme $body]
+ }
+ #
+ # 2) resolve the template along the "extends" chain
+ #
+ if {[info exists :extends]} {
+ return [${:extends} [current method] $name $theme]
+ }
+ #
+ # 3) if ending up here, report a missing template!
+ #
+ error "The template '$templateName' requested for \
+ renderer '[namespace tail [current]]' is \
+ not available."
+ }
+ }
+
+ :method readAsset {assetName} {
+ set assetDir [find_asset_path]
+ set assetPath [file join $assetDir $assetName]
+ if {[file exists $assetPath] && [file isfile $assetPath]} {
+ set fh [open $assetPath r]
+ set body [read $fh]
+ catch {close $fh}
+ return $body
+ }
+ }
+ #
+ # rendering
+ #
+
:method write {content path} {
set fh [open $path w]
puts $fh $content
@@ -1712,113 +1743,127 @@
}
file delete -force $path
}
+
+ :method installAssets {project theme targetDir} {
+ error "Not implemented. Instance responsibility!"
+ }
- :method place_assets {theme target} {
- # TODO: provide include/exclude filters based on [lsearch -glob -not]
- # set assets [lsearch -all -inline -glob -not $assets *.$ext]
- set assets [glob -directory [file join [::nx::doc::find_asset_path] $theme] *]
- file mkdir $target
- if {$assets eq ""} return;
- file copy -force -- {*}$assets $target
+ :method "layout many-to-1" {
+ project
+ theme
+ {-outdir [::nsf::tmpdir]}
+ } {
+ set fn [file join $outdir "[$project name].${:extension}"]
+ :remove -nocomplain $fn
+
+ set values [concat {*}[dict values [$project navigatable_parts]]]
+ lappend values $project
+
+ set output [list]
+ foreach e $values {
+ lappend output [:render $project $e $theme]
+ }
+ :write [join $output \n\n] $fn
+ :installAssets $project $theme $fn
+ puts stderr "$e written to $fn"
}
-
- :method "pick multifile" {
+
+ :method "layout many-to-many" {
project
- tmpl
+ theme
{-outdir [::nsf::tmpdir]}
} {
- set ext [namespace tail [current]]
- set theme [string trimleft [file extension $tmpl] .]
- set project_path [file join $outdir [string trimleft [$project name] :]]
+ set ext ${:extension}
+ #
+ # 1) provide a per-project output directory
+ #
+ set project_path [file join $outdir [string trimleft [$project name] :]]
:remove -nocomplain $project_path
if {![catch {file mkdir $project_path} msg]} {
-
+ #
+ # 2) place the theme-specifc assets into the project directory
+ #
set target $project_path/assets
- :place_assets $theme $target
+ :installAssets $project $theme $target
- set values [concat {*}[dict values [$project navigatable_parts]]]
#
- # Make sure that the @project entity is processed last.
+ # 3) Set-up the list of entities to be processed. Note that in
+ # this layout, the @project entity is processed along with all
+ # the other entities, but *last*.
#
+ set values [concat {*}[dict values [$project navigatable_parts]]]
lappend values $project
- # Note: We trigger the validation of entities according to
- # their pdata once for the entire entity hierarchy, starting
- # from the root, i.e. the project entity.
foreach e $values {
#
# TODO: For now, in templates we (silently) assume that we act
# upon structured entities only ...
#
- if {![$e info has type ::nx::doc::StructuredEntity]} continue;
- set content [:render $project $e $tmpl]
+ set content [:render $project $e $theme @project]
:write $content [file join $project_path "[$e filename].$ext"]
puts stderr "$e written to [file join $project_path [$e filename].$ext]"
}
}
}
- :method "pick singlefile" {
- project
- tmpl
+ :method "layout 1-to-1" {
+ project
+ theme
{-outdir "[::nsf::tmpdir]"}
} {
- set ext [namespace tail [current]]
+ set ext ${:extension}
set fn [file join $outdir "[$project name].$ext"]
- set theme [string trimleft [file extension $tmpl] .]
:remove -nocomplain $fn
- set content [:render $project $project $tmpl]
- :place_assets $theme $outdir
+ set content [:render $project $project $theme]
+ :installAssets $project $theme $outdir
:write $content $fn
puts stderr "$project written to $fn"
}
:public method run {
-project
- {-layout multifile}
+ {-layout many-to-many}
{-theme yuidoc}
args
} {
- # 1. trigger validation
+ # TODO: Relocate trigger validation!
$project validate
-
- # 2. verify whether there is ...
- # i) a layout handler and
- # ii) a template matching both the layout/theme specified
- set ext [namespace tail [current]]
- set tmpl $layout.$ext.$theme
- set path_to_tmpl [file join [::nx::doc::find_asset_path] $tmpl]
- if {![file exists $path_to_tmpl] || \
- [:info lookup method "pick $layout"] eq ""
- } {
- error "Beware, $ext $layout output for theme '$theme' not supported."
- }
-
- # 3) proceed
+ # --
:apply
- :pick $layout $project $tmpl {*}$args
+ :current_theme $theme
+ :layout $layout $project $theme {*}$args
:revoke
}
- :method render {project entity tmpl} {
+ :method render {project entity theme {tmplName ""}} {
error "Not implemented. Instance responsibility!"
}
}
Renderer create html {
- :method render {project entity tmpl} {
+
+ :method render {project entity theme {tmplName ""}} {
set top_level_entities [$project navigatable_parts]
set init [subst {
set project $project
set project_entities \[list $top_level_entities\]
}]
$entity current_project $project
- $entity render -initscript $init -template $tmpl
+ $entity renderer [current]
+ $entity render -initscript $init -theme $theme {*}$tmplName
}
+ :method installAssets {project theme targetDir} {
+ set assets [glob -directory [file join [::nx::doc::find_asset_path] $theme] *]
+ file mkdir $targetDir
+ if {$assets eq ""} return;
+ file copy -force -- {*}$assets $targetDir
+ }
+
+
#
# The actual refinements delivered by the mixin layer
#
@@ -1976,7 +2021,7 @@
set iscript [join [list [list set title $pof[join $pathnames .]] \
[list set source_anchor [join $pathnames { }]] \
[list set top_entity $top_entity]] \n]
- :render -initscript $iscript -template link.[:current_format].[:current_theme]
+ :render -initscript $iscript link
}
:public method as_text {} {
@@ -2128,9 +2173,7 @@
[list set source_anchor $print_name] \
[list set top_entity [current]] \
[list set cssclass nsfdoc-gloss]] \n]
- set res [:render \
- -initscript $iscript \
- -template link.[:current_format].[:current_theme]]
+ set res [:render -initscript $iscript link]
return $res
}
}; # NxDocRenderer::@glossary
@@ -2175,97 +2218,53 @@
}
}; # html::@method
- # MixinLayer::Mixin create [current]::@param -superclass [current]::Entity {
- # }; # html::@method
-
-
- }; # html
+ }; # html renderer
#
- # Provide a simple HTML renderer. For now, we make our life simple
- # by defining for the different supported docEntities different methods.
+ # An xowiki backend
#
- # We could think about a java-doc style renderer...
- #
-
- Class create HtmlRenderer -superclass Renderer {
- # render command pieces in the text
- :method tt {text} {return <@TT>$text}
-
- :method render=@package {} {
- puts "
+
+ [$project name]
+${:name} + [:? {[:info has type ::nx::doc::@package]} { + [:?var :@version {${:@version}} ] + } - { + [$project version] + }] +
+ [$project name] + [:? {[:info has type ::nx::doc::@package]} { + > ${:name} + } ? {[:info has type ::nx::doc::@class]} { + > [:?var :partof {[${:partof} name] >}] ${:name} + }] + +
+
+
+
+
+ [:? {[:info has type ::nx::doc::@project]} {
+
+
+ This is the API documentation for the
+ [:name] project.
+
+ [:include glossary]
+ } - {
+
+ [:include]
+ }]
+ Choose a package, object or command name from the list for more information.
+
+ [:include leftbar]
+
+
+
+ Copyright © [clock format [clock seconds] -format "%Y"] +
+ + Copyright © [clock format [clock seconds] -format "%Y"] +
\n[:text]" - set req [:@require] - if {$req ne ""} { - puts "
- "
- foreach r $req {puts "
- $r "} - puts "
\n[:text]" - # set variants [sorted [:variants] name] - # if {$variants ne ""} { - # puts "
- "
- # foreach v $variants {puts "
- [$v text]"} - # puts "
- "
- foreach v $params {puts "
- [$v tt [$v name]] [$v text]"} - puts "
\n[:text]" - if {[info exists :@method]} { - set methods [sorted [:@method] name] - if {$methods ne ""} { - puts "
Methods of ${:name}:\n
- "
- foreach m $methods {$v render}
- puts "
Object methods of ${:name}:\n
- "
- foreach m $methods {$v render}
- puts "
\n[:text]" - set params [:@param] - if {$params ne ""} { - puts "
- "
- foreach v $params {puts "
- [$v tt [$v name]] [$v text]"} - puts "