tcl'2003 doctools 10 th annual tcl/tk conference andreas kupries activestate corporation
TRANSCRIPT
© ActiveState Corporation 2003.
About ActiveState• ActiveState provides multi-language, cross-platform software and
services– Tcl, Perl, PHP, Python, XSLT– Linux, Solaris, Windows, HP-UX, AIX, …
• We make it easy to use new technologies– Web services and .NET
• Mission: Make Programming Easier– IDEs– Active distributions– ASPN
• ActiveState also provides flexible email management software for enterprises– Supports most UNIX platforms– Extensible in Perl– Spam and virus protection– Gateway protection
© ActiveState Corporation 2003.
Agenda
• Introduction
• Basics
• Internals
• TOC’s and Indices
• Limitations and Future
© ActiveState Corporation 2003.
The Problem
• Many formats in use– Nroff, HTML, Plain Text, XML, …
• Tcl-BLAST!– Latest attempt at unification– Tcl Manpage Markup Language (XML based)
• XML is considered heavyweight
© ActiveState Corporation 2003.
Our Solution
• DocTools = Yet more formats – Manpages, Table of Contents, Indices
• Ancestry– Conceptual: LaTeX (Semantic markup)– Implementation: Expand
• Where ?– SourceForge: Tcllib project.– Tcl (BSD) license
© ActiveState Corporation 2003.
Predefined output formats
• List (Metadata)• Semantic
– TMML - Tcl Manpage Markup Language– LaTeX– Wiki - Text format, using semantic markup
• Visual– Nroff– HTML– Text
• Users are free to define more formats !!
© ActiveState Corporation 2003.
Internals II
• Uses slave interpreters– For
• Common syntax checking
• Formatting engines
– Reasons• Separated functionality means easier maintenance of
the parts
• Security against bugs in formatters
• Against malicious intent too
© ActiveState Corporation 2003.
TOC / Index Autogeneration
• Tool: DocTools Processor (dtp)– SF Tcllib, TclApps, Starkit available at
http://mini.net/sdarchive/
© ActiveState Corporation 2003.
Limitations
• No true image support– Nothing for the text based formats– In HTML only through regular hyperlink <a>,
not as <img>.
• Not a true document management system– Basic include facility for text blocks– Document variables for parameterization– No management facilities
© ActiveState Corporation 2003.
Future I
• Add image support– Symbolic names, formatter selects actual file– Extend language with graphics commands
(vector drawings)
• More output formats– TIP, DocBook, ReST, PDF, doctools (!)– Tk Text Widget
© ActiveState Corporation 2003.
Future II
• Use doctools as intermediate format for other tools– Conversion from existing documentation– Literate programming
• Code + Documentation, extract the latter with a tool
• AutoDoc, zdoc
– Textual reports from code browsers• Source Navigator