#d2d 2.0 text using mtdocpage : webpage #title Collected White Papers on Technical Details --3-- #htmlTitle bandm metatools: Collected White Papers on Technical Details --3-- #lang en #tableOfContents // ========================================================================= #h1 #title Applications and Self-Applications, a Survey #h2 #title Table of Usage // ========================================================================= #p The following table does NOT mention the usage of #src!ops!, #src!format!, #src!message!, #src!dtd!, #src!dtm! and many other smaller packages, because these are ubiquituously engaged. The intention is to point out some #emph!paradigmatic! applications of the larger functional unities of #mt, which can be helpful for the uses as examples, documentation and inspiration. #nl A tabelaric survey is followed by some more detailed graphs of data flow. #table#border 1 #tr#td v uses -> #td pai #td umod #td fo-fr #td xantlr #td tdom #td metaJ #td LLjava #td muli #td opt #td tp/txsl #td d2d #td htmlMod #tr#td #td #td #td #td #td #td #td #td #td #td #td #td #tr#td dtd #td #td X #td X #td #td #td #td #td #td #td #td #td #tr#td xantlr #td #td #td #td -- #td #td #td #td #td #td #td #td #tr#td metajava #td #td #td (X1) #td X #td #td -- #td #td #td #td #td #td #tr#td tdom #td #td #td #td #td -- #td #td #td #td (X2)#td #td #td #tr#td formatfrontends #td #td #td -- #td X #td X #td X #td #td #td #td #td #td #tr#td muli #td #td #td #td #td X #td X #td #td #td #td #td (X3) #td #tr#td option #td #td #td #td #td X #td X #td #td #td #td #td (X3) #td #tr#td umod #td #td -- #td (X1) #td X #td X #td X #td #td #td X #td #td #td #tr#td tpath #td #td X #td -- #td X #td X #td #td #td #td #td #td #td #tr#td xslt #td #td #td #td #td X #td #td #td #td X #td X/-- #td #td #tr#td d2d #td #td X #td (X1) #td X #td X #td #td #td #td X #td X #td -- #td #tr#td umod #td #td -- #td (X1) #td X #td X #td X #td #td #td X #td #td #td #tr#td #td #td #td #td #td #td #td #td #td #td #td #td #tr#td dtm/htmlRenderer #td #td #td (X1) #td #td X #td #td #td #td X #td #td #td X #tr#td book2 #td #td X #td #td #td X #td #td #td #td X #td #td X #td X #tr#td DemoMetric #td #td X #td #td #td #td #td #td #td X #td #td #td #tr#td MfMain #td #td X #td #td #td #td #td #td #td X #td #td #td //Haken #tr#td gongMachine #td #td #td #td #td #td #td #td X #td X #td #td #td //ttc2011 case 1/2/4 #tr#td wiki #td #td #td #td #td X #td #td #td #td #td #td X #td X //na meeli //rtl dsl #tr#td rezept #td #td #td #td #td X #td #td #td #td #td #td X #td X #tr#td #td #td #td #td #td #td #td #td #td #td #td #td #tr#td sig #td #td #td #td #td #td #td #td #td #td #td #td #tr#td tscore #td #td #td #td #td #td #td #td #td #td #td #td #tr#td MORETOCOME #td #td #td #td #td #td #td #td #td #td #td #td #/table #p Remarks: #nl (X1) metajava/the users of metajava heavily use "format", but not the front-end compiler. #nl (X2) tdom uses "option" after a second bootstrap cycle. #nl (X3) users of "muli" and "option" frequently use "d2d", after completion of the bootstrap cycle. #nl // ========================================================================= #h2 #title Some paradigmatic data flows // ========================================================================= #p#kind src For these flow diagrams see also /src/eu/bandm/d2d2/TODO and /doc/internal/README #p A very versatile pattern is the following, which happens in the complete and in a shortened form: #source ] d2d ] tdom javac .ddf -----]--> .dtd -------> .java -----> ] .xml----\ d2d \ HANDCODED .d2d ----------------->sax---------+--> objectModel ===============> output tdom \ / ----> aux Data -- HANDCODED #/source #p The #xemph!long form! works as follows: #nl Nearly all sources are generated from an initial ".ddf" d2d-text-type definition automatically. #nl The input data is encoded in d2d format and directly fed into the tdom model, with a few lines of top-level code. #nl The "auxData" are "diagonal vertices" in the tdom graph, i.e. additional directories, maps, indexes, etc., constructed by hand coding. #nl In most cases this pattern is very efficient: only few additional data must be generated, the generated visitor pattern can heavily be exploited, resulting in few lines of user code. #p #src!eu,bandm.book2!, #src!de.na-berlin.meeli!, #src!eu.bandm.rezept! #src!eu.bandm.wiki! work this way. #p An esp. interesting case is when an XHTML model is the generated output (#src!rezept!, #src!wiki!). Here one tdom model is transformed into a different one. #p (Older examples are #src!pameca/docusoft/src/al/org/pameca/docusoft/docu_metadata.dtd! and #src!eu/bandm/tools/jul!.) #p The method which realizes the functionality of "data 2 tdom", callable by alle these applications, is #link 2/eu/bandm/tools/d2d2/base/Tasks.html #loc text2tdom-java.io.File-eu.bandm.tools.d2d2.base.ModuleRegistry-java.lang.Class-D-eu.bandm.tools.message.MessageReceiver-eu.bandm.tools.d2d2.base.Text2Udom.ErrorStrategy-int- #text#src static eu.bandm.tools.d2d2.base.Tasks.text2tdom(..) #/link. // FIXME xhtml generierung macht SCHLUSS bei loc nach "text2tdom-java." ????? #p The most complex example is the #src!txsl! xslt interpreter: its operation is nothing more than a transformation (expansion) of the original tdom model of the xslt code. #hr // ------------------------------------------------------------------- #p The #xemph!shortened form! starts with a DTD for generating tdom. #nl The input data normally is an XML file, in the standard encoding. #nl Nevertheless, this file can also be generated by d2d parsing, controlled by the dtd. #nl This pipelining can happen internally, controlled by the application, or externally in the file system, controlled by "make" etc. This does not make any difference in the logical of the data flow. #p In this way #src!tools.option! and #src!tools.muli! are implemented. They are used as follows #table#border 1 #tr#td v uses -> #td option #td muli #tr#td #td #td #tr#td DocumentedDistribution #td #td handwritten XML #tr#td umod #td handwritten XML #td #tr#td dtd renderer #td handwritten XML #td #tr#td xslt #td handwritten XML #td #tr#td d2d/base #td handwritten XML #td #tr#td d2d/gui #td #td d2d-encoded #tr#td #td #td #tr#td book2 #td handwritten XML #td d2d-encoded #tr#td music..DemoMetric #td d2d-encoded #td #tr#td music..MfMain #td handwritten XML #td #tr#td gongmachine #td handwritten XML #td #tr#td na meeli #td d2d-encoded #td d2d-encoded #/table // ========================================================================= #h1 #title Coding Rules // ========================================================================= #commentchar\ #p The general rules of code design can be taken from our theoretical papers. #p Here only a few of the theoretical guidelnes: #nl (Perhaps later more to come!?!? FIXME) #list #i Normally "functional" style shall be preferred, which passes parameters explicitly and makes data-flow completely visible by one glance to the method's declaration. #i Whenever possible, point-free formulations shall be preferred, e.g. by using the #src!tools.ops! library, etc. #i Assumptions about the incoming state of parameters and fields should be made explicit by inserting #src!assert ...! #i Data types shall be cleanly defined as "algebraic" and "immutable", or "object style". They must be encoded accordingly, i.e. with protected fields and restricted setter methods. Normally algebraic/immutable is preferable. #/list #p The following rules are just technical, about the details in writing. They may seem overspecified but turned out to be very sensible, esp. for maintainability. #list #i Source code is written with indentation. The indentation is left to the editor (normally XEmacs) with an ident amount of two(2) spaces. #i Variables must have talking names. Whenever appropriate the name of a "global" variable should be the name of its type, with lower case initial character. #nl One-character variable names are only possible for very narrow scopes of few lines. #i Reference type declarations of variables, fields, parameters and results must be prefixed by #src!/*opt*/! if the normal operation includes the value #src!null!. (This corresponds to type declarations "opt()" in more precise programming languages.) #i All parameters, fields, variables must be declared #src!final! whenever possible. (This turned out to be incredible helpful when reading third-party or older own sources!-) #i Parameters should always be declared #src!final! and not reused as local variables. #i While "functional style" is preferred, some types of problems are easier written using object style and global fields. There, field values can be used in the very middle of some method code. It can be very sensible to make these accesses explicit by adding comments mimicking declarations, as in #ldots#nl #src! public void myMethod (final int a, !#nl #src! /*glo in field1, glo in out field2*/){ ...! #i Temporal trace output "instrumentation" shall be prefixed by #src!/**/!, for easy grepping and elimination. #/list The indentation #eof