Tcl'2003

DocTools

10th Annual Tcl/Tk Conference

Andreas Kupries

ActiveState Corporation

© 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.

Example I: SHA1 Manpage

© ActiveState Corporation 2003.

Example II: Table of Contents

© ActiveState Corporation 2003.

Example III: Index

© 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 I

© 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.

Example: TOC

© ActiveState Corporation 2003.

Example: Index

© 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

© ActiveState Corporation 2003.

Acknowledgements

• William Duquette, for “Expand”

• Joe English, for advice and help