TmDoc - maintenance document producer for Ruby software

[ ENGLISH | JAPANESE ] [ Link to: RAA Entry ]

Wellcome to TmDoc project's home page!!

• Ruby 1.8.7 (1.9 isn't tested yet)
• XSLT processor (example, xsltproc)
• DocBook V4.5 style sheet

Standard setup.rb procedure.

  $ tar xfz tmdoc-X.X.X.tar.gz
  $ cd tmdoc-X.X.X
  $
  $ ruby setup.rb config
  $ ruby setup.rb setup
  $ sudo ruby setup.rb install

(1) Create output directory

  $ mkdir dbook

(2) Run tmdoc command

  $ tmdoc foo.rb

(3) Convert the generated DocBook files to HTML format

  $ xsltproc --xinclude $DOCBOOK_XSL_DIR/html/docbook.xsl dbook/tmdoc.home.docbook > foo.html

• For description of tmdoc command options, see TmDoc manual.
• More useful usage, see below section: Examples.

Examples

Common files: README.txt, Makefile, Make.Common, Make.Rules, dbook-to-html.xsl, tmdoc.css

Name	Description	Download	Related files	TmDoc options	Log file
Net	Network client library (Ruby 1.8.7 standard library)	EPUB	Makefile __dummy__.rb	-	LOG.txt
REXML	XML parser library (Ruby 1.8.7 standard library)	EPUB	Makefile __dummy__.rb	--tab-width 2	LOG.txt
RubyTk	GUI toolkit (Ruby 1.8.7 standard library)	-	Makefile __dummy__.rb	--show-class-siblings	LOG.txt
WEBrick	Web server toolkit (Ruby 1.8.7 standard library)	EPUB	Makefile	--show-all	LOG.txt
databasedotcom 1.3.0	A ruby wrapper for the Force.com REST API	EPUB	Makefile	--show-all	LOG.txt
ActiveSupport 2.3.14	Utility classes and Ruby extensions from Rails	-	Makefile __dummy__.rb	-	LOG.txt
The Depot Online Store	This application implements an online store, with a catalog, cart, and orders. An example Rails application that is described in the book: "Agile Web Development with Rail (3rd edition)". It can get the source code from publisher's download page.	EPUB	Makefile __dummy__.rb	--show-all	LOG.txt
Radiant 1.0.1	Content Management System	-	Makefile __dummy__.rb	--show-module-siblings	LOG.txt
Redmine 1.4.0	Flexible project management Web application	-	Makefile __dummy__.rb	-	LOG.txt
TmDoc 0.0.4	Maintenance document producer for Ruby software	-	Makefile Make.FILES	--show-all --tab-width 4	LOG.txt

The document of EPUB edition was converted from DocBook format, using BOOKSHOP(bookshop-0.0.4).

[Notice]	In the latest release of BOOKSHOP(bookshop-0.0.18), the support of DocBook was aborted, it seems .... orz Related article: bookshop gem drops docbook for html : RubyFlow on November 17, 2011

Notes for TmDoc Hacking

Software Architecture
Logical Space Model(LSM)
Scanner and Parser

Software Architecture

The TmDoc system is designed based on "layered pipeline architecture".

Key components in the system are "Model(Module: Model (TmDoc))" and "Transformer(Module: Transformer (TmDoc))". The "Model" is a immutable object strong-typed by Logical Space Model(LSM) declaration, and the "Transformer" is a function that transform a model object into another model object.

• [Input File] Ruby source code files
  • /Reader/ Module: Reader (TmDoc) -- Read source code
• [Model] Module: Core (TmDoc::Model) -- Data type of core model
  • (Transformer) Module: CoreIntoModule (TmDoc::Transformer) -- Transform core model into module model
• [Model] Module: Module (TmDoc::Model) -- Data type of module model
  • (Transformer) Module: ModuleIntoObject (TmDoc::Transformer) -- Transform module model into object model
• [Model] Module: Object (TmDoc::Model) -- Data type of object model
  • (Transformer) Module: ObjectIntoDocument (TmDoc::Transformer) -- Transform object model into document model
• [Model] Module: Document (TmDoc::Model) -- Data type of document model
  • (Transformer) Module: DocumentIntoDocBook (TmDoc::Transformer) -- Transform document model into DocBook model
• [Model] Module: DocBook (TmDoc::Model) -- Data type of DocBook model
  • /Writer/ Module: Writer (TmDoc) -- Write DocBook document
• [Output File] DocBook document files

The term "layered pipeline architecture" is a compound term from "layered architecture" and "pipeline architecture". The following book conside the details of benefits and weaks of these architecture:

"Pattern-Oriented Software Architecture Volume 1: A System of Patterns",
Frank Buschmann/Regine Meunier/Hans Rohnert/Peter Sommerlad/Michael Stal, John Wiley & Sons, Ltd., 1996

Logical Space Model(LSM)

The Logical Space Model, LSM(Module: Lsm (TmStd)) is a Ruby implementation of abstract data type introduced by following old publication:

"Software Specification and Design Method Based on Integrated View of Structure Standardrization" [in Japanese]
Kataoka, M., Miyamoto, K., Kondo, H., Yamano, K., IPS of Japan Vol.25 No.11 (Nov. 1984).

Scanner and Parser

The Ruby code scanner(Class: Scanner (TmDoc::Reader::Ruby18)) and parser(Module: Parser (TmDoc::Reader::Ruby18)) are based on RDoc's code that is a Ruby standard library and de-facto Ruby standard documentation system, written by Dave Thomas.

The origin of RDoc's parser code was written by KEIJYU Isitsuka (cite from README attach to RDoc). This original code is based on classical technique which is generally called "recursive descent parser". In the following book, the code is descripted by the developer's self:

"Object-Oriented Scripting Language Ruby (ASCII SOFTWARE SCIENCE Language)" [in Japanese],
Yukihiro Matsumoto/Keijyu Ishitsuka, ASCII CORPORATION, 1999, ISBN4-7561-3254-5

---

[ HOME ]