deplate 0.7.3 → 0.8

data/TODO.TXT

@@ -1,68 +1,162 @@
 * Problems & issues
-** Current
-    #A _ Apply CH's patch, prepare the source to better support his changes
-    #A _ A "notice" within a list breaks the list in two -- this shouldn't be 
-         the case (CH's patch should solve this)
-    #A _ International characters in simple wiki names do not work properly
-    #B _ check for potential code injection (when using eval)
-    #B _ Use Deplate::Cache for ''Deplate::Regions::DefElement''
-    #C _ Handling of backslashes in ''DefMacro''
-    #D _ ''#DefElement'' & ''#DefParticle'': Does it work with strange 
-         characters? Are the Rx properly escaped etc.?
-    #D _ Misplaced hyperlinks in "BibTeX-files"
-
-*** Docbook
-    #C _ check for invalid xreflabels
-
-*** HTML
-    #C _ bibliography & html output: @incollection; @misc without author/editor
-
-*** LaTeX
+    #A2 _ ''[[#textpipe][TextPipe]]'' generates wrong link when splitting 
+      output (''[[integration#textpipe][TextPipe]]'' is okay though)
+    #A4 _ Find a way to respect whitespace at the beginning of a macro's 
+      argument, e.g.
+        - ''{text: \ bla}'' -> currently generates a non-breakable space
+        - ''{text exact!: bla}''
+        - ''{text:: bla}''
+
+    #A5 _ #INC: look in the directory of the input file first
+    #A7 _ Wrong numbering when defining a heading as an example's title 
+      (level_as_string gets lost somehow or is not updated right in time)
+    #A7 _ Latin-1 umlauts are sometimes translated to utf-8, when including a  
+      document-- I have no idea what is causing this
+    #A9 _ Duplicate anchors
+        - Regions.html: - r_geyser	914, 917
+            - dot_example	906, 909
+            - \InlatexExample	1036, 1037
+            - InlatexExampleXY	1040, 1043
+        - The Bib
+            - mynona__p1	158
+            - mass4	159
+    #A9 _ The ref macro inserts a heading number even if ''headings'' is set 
+      to "plain"; running numbers are also used in auto-generated labels which 
+      is wrong.
+
+    #B1 _ Disable #Native in templates (why/when was it enabled?)
+    #B1 _ Handling of multi-file output is still a mess
+    #B1 _ Check for potential code injection (when using eval & 
+      Deplate::Cache)
+        - check if we can use Deplate::Cache without evaluating strings
+        - places where user input finds its way into the output
+            navbar-png.rb :: variables['buttonsColour'], 
+              variables['buttonsFileFormat']
+        - this calls for a general validation framework, I'd say
+    #B3 _ All File.open & File.exists should be replaced with wrapper 
+      functions; depending on some allow flags these functions should restrict 
+      access to:
+            1. the directory of auxiliary files
+            2. || $PWD + subdirectories
+            3. || the current input file's directory || the output directory
+            4. || any directory
+    #B5 _ Further checks if international characters in simple wiki names now 
+      really work
+    #B5 _ ''#DefElement'' & ''#DefParticle'': Does it work with strange 
+      characters? Are the Rx properly escaped etc.?
+    #B7 _ Check if calling "services" from the document (not the template) 
+      works (most likely not)
+        - this should probably be renamed to something like template 
+          function/helper and restricted to templates
+
+    #C2 _ Do we still need @dest? @dest vs. @options.out vs.  
+      @output.destination: One should be enough.
+    #C4 _ Skeletons vs. services vs. #INC: this is kind of redundant
+    #C5 _ Currently, deplate converts a document in three steps; this is wrong 
+      because it introduces too much complexity just to avoid running deplate 
+      three times � la LaTeX; there should be only one step and the 
+      saved/cached metadata should be used for setting references and the 
+      like. Basically, running a single-step deplate two times should be 
+      sufficient to get everything right.
+        - deplate should be able to automatically check if the newly created 
+          metadata and the previous one converge and stop if they do or if a 
+          certain threshold was surpassed (can't converge error).
+    #C7 _ Improved support for symbols: input vs. output encoding
+    #C7 _ Symbols & locales: The conversion table should be contained in the 
+      DATA section, not in some extra file
+    #C8 _ lists: don't tranform list items to structs but accumulate the items 
+      right away
+    #C9 _ HTML: use entities for special characters (e.g. ü instead of 
+      �) -- the problem with this currently is, that we have to know the input 
+      encoding in order to compile a conversion list; an alternative approach 
+      would be to convert everything to utf8 internally but this whould rely 
+      on iconv which is not available on all platforms (at least not in the 
+      default ruby installation)
+
+    #E3 _ #Math region (similar to \{math\} macro but at the block/element 
+      level)
+    #E4 _ {var} ~~ {arg: var} || {get: var}
+    #E4 _ {val:} vs. {var:} vs. {arg:} vs. {xarg:} vs. {get:} vs. {opt:}
+    #E4 _ variables vs. clips
+    #E4 _ Check if an #IF command finishes an element
+    #E4 _ {cite an!: xxx} -> X & Y~(2000)
+    #E4 _ citation styles
+            - numbered � la uniform medical submission requirements ...
+            - implementations: prefixed (=style) methdos:
+                - eg: apa_cite
+                    - if ''STYLE_method'' doesn't exist -> Fallback: 
+                      ''default_method'' or simply ''method''?
+    #E4 _ #MAKEBIB -> #LIST: bib
+    #E4 _ #Style -> Mark text in region with style attribute
+
+    #F3 _ chaining formatter; reimplement the way particles are formatted
+    #F5 _ check how inlatex-compound can be made more robust (and make it the 
+      default for dealing with inline latex bits)
+    #F9 _ Regions should be handled differently so that nested regions can use 
+      \#End.
+
+** Docbook
+    #A _ deplate complains about a malformed list (toc, lot, lof?) or internal 
+      error when compiling the manual
+    #C _ docbook support for styles (e.g. for task lists) (well, how? role?)
+    #D _ docbook support for custom lists
+
+** HTML
+    #A _ If an indexed word is moved to a list (#LIST), then the index points 
+      to the wrong position.
+    #B _ The #AUTOIDX command should not create an index entry for itself. 
+      (Wasn't this already fixed?)
+    #F _ Option to insert line numbers as labels
+
+** LaTeX
+
+** PHP
+    #B _ Propagate the get arguments -> Base url should be a format string.
+
+** Plain text
 
 ** Other
-    #C _ relative/absolute file names & urls in the \{img\} and #IMG: define 
-         proper behaviour
-    #C _ plain headers mustn't increase the heading index
-        - but this currently interferes with some other mechanisms (I'm not 
-          sure if this is still true)
+    #B _ plain headers mustn't increase the heading index
+        - but this currently interferes with some other mechanisms (this was a 
+          problem in the past, I'm not sure if this is still true)
     #C _ define how convert_string should work when invoked repeatedly (with 
-         respect to #IDX, #ABBREV, ...)
-    #C _ manual-sf: I don't understand what causes: "Index: Neither file nor 
-         level defined: dropping: idx001"
+      respect to #IDX, #ABBREV, ...)
+    #F _ custom names for labels/refs (html output)
+            - or use extended wiki names instead
+    #F _ relative/absolute file names & urls in the \{img\} and #IMG: define 
+      proper behaviour
+            - general solution or formatter specific (as it is now)?
+
+
+** Tests for ...
+    - Test cases for file handling (in, out, stdin, stdout)
+    - "services"
 
 
 * TODO
-** 0.7.4
-    - Every element should know its original indentation level (if it doesn't 
-      already)
+** 0.09
+    - test output to sciposter (or similar) for LaTeX output
+    - define a way to create a slot from within a deplate document
+    - \FreeMind output
+    - \OpenDocument or RTF output (if rtf.rb can be used for this)
     - Method/attribute naming: indentation vs. level (heading)
-    - Rethink the way lists work (prepare generalized solution for: embedded 
-      elements � la CH's patch; priority lists � la emacs-planner)
-    - Incorporate Csaba Henk's patch
-    - emacs-planner style task lists (as module because of a slight ambiguity  
-      with the markup of commands)
-
-** 0.8
-    - #VAR should set the variable during #process & #print too, so that 
-      variable handling is more intuitive
-    - unify region & command
-    - don't forget/skip creating test cases
+    - Metadata-related stuff should be re-implemented (and made more useful)
+    - Two-pass single-step redesign
     - citation & bibliography styles
-    - HTML: make indexed words be hyperlinked to the index (~~tag cloud)
-    - module inlatex-compound.rb: Inlatex, ltx, math: all latex bits are 
-      collected in one file, compiled in one big dvi file and then separated 
-      into graphical output (partially done but not fully working yet)
     - the output stuff has to be managed by the formatter class alone
-    - a null formatter that doesn't generate any output at all (to be used in 
-      conjunction with modules that generate/scan metadata and do nothing 
-      else)
+    - HTML: make indexed words be hyperlinked to the index (~~tag cloud)
+    - HTML: bib entries should have backlinks to where an author was cited
+    - PHP: mysql backend for the comment facility (per page, element)
 
-** 0.9
-    - Metadata-related stuff should be re-implemented (and made more useful)
-    - ''if'', ''ifelse'' macros
-    - fully document the code
-    - define a way to create a slot from within a deplate document
+** 0.10
+    - unify region & command & anchor
+        - unify region & command
+        - if it isn't a region/command, check if it could be an anchor
+        - make it case insensitive
+        - or leave it the way it is
     - allow addressing slots by name only
+        - make slots "relative" so that something like begin+5 and end-6 can 
+          never overlap.
     - make autoidx a particle of its own with a volatile rx saved in the 
       current instance of Deplate::Core (don't create new classes) -- the rx 
       should be a property of Deplate::Core though
@@ -72,15 +166,11 @@
     - clean up deplate.rb (handling of @sources, \--each, \--many is ...  
       suboptimal)
     - reconsider the way indexes & clips & footnotes etc. work
-    - make a nice slides css/template that can be used for presentations
-    - test output to sciposter (or similar) for LaTeX output
     - text blocks that can be freely placed on a page (at least for HTML & 
       LaTeX)
 
 ** 1.0
-    - check doc variables/parameters for consistent naming
-    - in automatically inserted Text, words in \CamelCase mustn't be translated 
-      to wiki names?
+    - check variables for consistent naming; define synonyms if necessary
     - LaTeX
         - dense08: decrease the line spacing too
         - longtable
@@ -92,8 +182,7 @@
     - HTML + LaTeX: wrap text around floats (tables, figures)
 
 * Additional classes for improved functionality
-    - "Priority lists" (� la planner mode)
-    - Widgets: Calender, Forms (HTML only?)
+    - Widgets: Calender, Forms (HTML/PHP only?)
 
 * Additional classes for better support of other wiki markups
     - bold
@@ -109,19 +198,13 @@
     - other text styles: underline, strike through ...
 
 * Other ideas
-    - additional markup classes
-    - support for additional wiki markups
-    - make the xmlrpc module handle files in subdirectories???; actually test 
-      it
-    - make a php-based wiki that uses deplate via xmlrpc
-    - command line options
-        --cfg :: load a custom configuration file
-        --local-cfg :: allow a directory local configuration file tree
-    - htmlsite: make it possible break output at level 2,3... headings too
-    - generalize the concept of captions & table of contents; make it possible 
-      to define arbitrary tables/lists
-        - #CAPTION class=NAME: TITLE
-        - #LIST: NAME
+    - ''if'', ''ifelse'' macros (or define a region (e.g., #Particle) that 
+      evaluates its body as template and parses the result as inline text, 
+      yielding some particles which are appended to the previous element's 
+      body).
+    - plain text: ascii representation for images
+        - support for more formatters (eg aalib) & find a pure ruby solution
+        - find a way to convert vector based formats
     - #A, #ANCHOR command
         - integrate with ctags
     - #ACRONYM ... Glossar and acronyms
@@ -130,17 +213,13 @@
       already the default?)
     - #Filter ... (general region) filter region through an external program, 
       insert result as verbatim, image, table etc.
-    - String patch Deplate::String ("bla".to_html)
     - html: backreferences from the bibliography to the citation
     - html: citation/bibliography styles?
-    - are 3 passes necessary? 2 would probably be sufficient and make things 
-      easier.
     - a way to define page layouts (it should at least be possible to make 
       posters/slides using a html/latex/context formatter)
     - Define styles in deplate
-    - poor man's static blog: put articles in folders (YEAR/MONTH/DAY/ID/); 
-      generate main page (incl menu) + rss with the newest articles; static 
-      calender (or use \JavaScript?)
+    - colours (or maybe not; abstract styles are probably better)
+        - Use classes in html, colours in other output formats
     - rss somehow?
         - Mod: rss-item. Erzeugt Region ''#RssItem title=TITLE, desc=@body''.  
           Die Items werden mit erstmaligen Datum + Url (im Text hinterlassen 
@@ -154,25 +233,26 @@
           interpretiert.
             - Nachteil, dass man genaue URLs angeben muss, wo das RSS Item 
               hinzeigt.
+        - Mod: rss-auto: Maintain a list of sections + date; determine 
+          automatically, which sections are new/have changed
     - The syntax of regions vs. commands vs. macros is stupid -> unify!  
       (problem of the use of # for anchors, commands, and regions, which could 
       be solved by disallowing text/comments following an anchor or by 
       defining a #A command)
-    - colours (or maybe not; abstract styles are probably better)
     - Option to keep/convert comments
-    - region: Hash
-      - Like a description list, but the content is saved as a hash doc option 
-        (or use XML, YAML, or plain ruby syntax instead?)
-    - region: \ListAsTable
-        - 1 level items = rows: head, body, foot
-        - 2 level items = cells
-            ??? Or do it like phpwiki's definition list tables?
     - better markup for tables (yet unseen/unknown)
+        - eg region: \ListAsTable
+            - 1 level items = rows: head, body, foot
+            - 2 level items = cells
+                ??? Or do it like phpwiki's definition list tables?
     - formatter "state": block/element - inline/particle, mathematical - text
+    - make the xmlrpc module handle files in subdirectories???; actually test 
+      it
+    - make a php-based wiki that uses deplate via xmlrpc
     - write a wiki server or a deplate plugin for some existing wiki
     - write a general source code documentation tool that uses deplate markup 
       -- or bend rdoc to do so
-    - markup for math stuff
+    - markup for math stuff (� la ASCIIMath but for all output formats)
 
 * Support for additional formats (in & out)
 ** In
@@ -184,9 +264,12 @@
     - rd
     - markdown
     - textile
+    - xml
+        - \FreeMind
 
 ** Out
     - \OpenDocument
+    - \FreeMind
     - direct pdf output via the pdf-writer library
     - rtf formatter (only if it can be done better than docbook+jade does and 
       if it is easier to implement than an \OpenDocument formatter)
@@ -194,6 +277,9 @@
       a roundtrip like deplate -> latex -> deplate doesn't produce too much 
       noise)
 
+** Etc.
+    - Text_Wiki::Deplate class (in php, yuk)
+
 
 % @Last Change: 07-J�n-2005.
 % vi: ft=viki:tw=78

data/VERSION.TXT

@@ -1 +1 @@
-0.7.3-2132
+0.8final-2711

data/etc/deplate.ini

@@ -1,6 +1,6 @@
 ; % * deplate.ini
 
-; % This is the ini file for deplate. It doesn't adhere to the section 
+; % This is the ini file for ''deplate''. It doesn't adhere to the section 
 ; % format usually used in ini-files. Instead it consists of simple 
 ; % commands or variable definitions. If you need to do something more 
 ; % sensible like making a variable's value dependent of the computer 
@@ -35,13 +35,36 @@
 ;    autoindex :: Enable automatically adding entries to index (BOOLEAN, 
 ;       default: false)
 
+;    autoBaseName :: In multi-file output, deduce the output filename 
+;       from the current input file (BOOLEAN, default: false)
+
 ;    autoFileNames :: Enable automatic generation of file names based on  
 ;       the top heading for multi-file output (BOOLEAN, default: false)
 
+;    auxiliaryDir :: If defined, auxiliary files will be put into  
+;       this subdirectory (STRING)
+
 ;    auxiliaryDirSuffix :: If defined, auxiliary files will be put into  
 ;       a subdirectory named after the base name of the root file plus this 
 ;       suffix (STRING)
 
+;    bibClickableCitation :: Whether citations (eg in HTML output) are 
+;       clickable hyperlinks (BOOLEAN, default=false)
+
+;    bibStyle :: Default bibliography style (STRING)
+
+;    bibSepAuthors :: The separator for author names (STRING, 
+;       default="; ")
+
+;    bibSepLastAuthor :: The separator for the last author name (STRING, 
+;       default="; ")
+
+;    bibSepTwoAuthors :: The separator between two author names (STRING, 
+;       default="; ")
+
+;    bibSepName :: The separator between prename and surname (STRING, 
+;       default=", ")
+
 ;    class :: The document class; used in LaTeX (= document class) or 
 ;       HTML output (= CSS) (STRING)
 
@@ -54,6 +77,10 @@
 
 ;    docBasename :: The base name of the output document (STRING)
 
+;    elementStyle :: If set to 'block', the markup of styles changes. For 
+;       LaTeX output, this make ''deplate'' use regions. You can set this 
+;       for single elements too. (STRING)
+
 ;    embeddedTextRx :: A regular expression matching embedded text 
 ;       (submatch $1) (REGULAR EXPRESSION)
 
@@ -65,12 +92,29 @@
 ;       LaTeX :: latin1
 ;       XML   :: UTF-8
 
+;    figureNumbering :: How figures should be numbered (STRING)
+;       flat, document :: One counter for all figures
+;       none           :: No numbering
+;       section (DEFAULT) :: Per section
+
 ;    floatAlign :: The default alignment of floats; dependent on the 
 ;       output format (STRING)
 
 ;    headings :: The headings style (STRING)
 ;       plain :: Don't number headings
 
+;    homeIndex :: The heading index that should be the home page in 
+;        multi-file output (INTEGER; default: 0)
+
+;    hyperHeading :: If set and a heading has an ''url'' option 
+;        attached, turn the heading into a hyperlink; if set to "full", then 
+;        heading is used as link text, which may result in invalid output; 
+;        otherwise a button is attached to the heading (BOOLEAN or 
+;        STRING){lab: hyperHeading}
+
+;    hyperHeadingButton :: The text for hyperlinked headings (STRING; 
+;        default: =>)
+
 ;    imgSfx :: The default suffix for images (STRING, default: png)
 
 ;    indexwiki :: If "no", don't autoindex extended wiki links (STRING)
@@ -82,6 +126,10 @@
 ;    inlatexHeight, inlineLatexHeight :: Define the ''h'' parameter of 
 ;       images generated by an inline LaTeX snippet (NUMBER)
 
+;    ltxPointsize :: The pointsize used for LaTeX snippets; this can be  
+;       overridden by a per-element 'pointsize' argument; see also 
+;       [[#ps2imgRes][ps2imgRes]] (NUMBER, default: 10)
+
 ;    ltxSfx :: The suffix of images generated by an inline LaTeX snippet 
 ;       (STRING, default: dependent on the output format)
 
@@ -93,16 +141,27 @@
 ;    ltxPrelude :: Like ''inlatexPrelude'' but used for the ''ltx'' 
 ;       macro only
 
+;    mandatoryID :: If set, elements that create auxiliary files must 
+;       have an ID (BOOLEAN)
+
 ;    mathPrelude :: Like ''inlatexPrelude'' but used for the ''math'' 
 ;       macro only
 
 ;    noExplicitNumbering :: Ignore the explicit numbering in lists (BOOLEAN)
 
+;    particleStyle :: If set to 'span', the markup of styles changes.
+;       For LaTeX output, this make ''deplate'' use proper commands. You 
+;       can set this for single particles too. (STRING)
+
 ;    pdfOutput :: Automatically set when using pdf output (the ''--pdf'' 
 ;       command line switch) (BOOLEAN)
 
+;    prefixID :: Prefix autogenerated names for auxiliary files with 
+;       this string; if not defined, use the current document's base 
+;       name (STRING)
+ 
 ;    ps2imgRes :: The resolution used for converting postscript files to  
-;       bitmaps, e.g., by ps2ppm (NUMBER, default: 96)
+;       bitmaps, e.g., by ps2ppm (NUMBER, default: 120){lab: ps2imgRes}
 
 ;    refButton :: String to be used to represent the wiki references 
 ;       (STRING)
@@ -120,6 +179,11 @@
 ;       referenced by wiki names (STRING)
 ;       - <+TBD+>This will be subject of change
 
+;    tableNumbering :: How tables should be numbered (STRING)
+;       flat, document :: One counter for all figures
+;       none           :: No numbering
+;       section (DEFAULT) :: Per section
+
 ;    tableStyle :: The default style for tables (STRING)
 
 ;    tabwidth :: The tab width used when expanding whitespace (NUMBER, 
@@ -135,6 +199,7 @@
 
 ; *** Output Format
 ; **** HTML
+
 ;    baseUrl :: The document's base url (STRING)
 
 ;    baseUrlStripDir :: Number of directories to remove when adding a 
@@ -159,6 +224,9 @@
 ;    homeButton :: The "home" button in the navigation bar 
 ;       (STRING, default: [-])
 
+;    htmlAuxUrl, htmlCssUrl, htmlImgUrl :: Format string that defines the 
+;       URLs for images, CSS etc. (STRING)
+
 ;    metaDataExtra :: Other HTML code to be inserted 
 ;       at head position (STRING or ARRAY OF STRINGS)
 
@@ -193,11 +261,23 @@
 
 ;    shortcutIcon :: The shortcut icon tag (STRING)
 
+;    stepwiseDisplay :: Whether to display a page step by step (BOOLEAN, 
+;       default: false)
+
+;    stepwiseBegin :: Number of initially visible elements (INTEGER, default: 
+;       1){lab: stepwiseBegin}
+
+;    stepwiseContinous :: Automatically move to the next page if all elements 
+;       are displayed (BOOLEAN, default: false)
+
+;    stepwiseKey :: Key code for revealing the next element (COMMA-SEPARATED 
+;       LIST; default: 78 = 'n'){lab: stepwiseKey}
+
 ;    styleExtra :: Some extra CSS information that will be wrapped in a 
 ;       style tag (STRING or ARRAY OF STRINGS)
 
 ;    subToC :: Print a table of contents for the current section after 
-;       level 1 headings (BOOLEAN, default: false)
+;       top level headings (BOOLEAN, default: false)
 
 ;    tabBar :: Items in the navigation bar (ARRAY OF STRINGS, 
 ;       default: ["[auto]"])
@@ -263,6 +343,12 @@
 ;    tableFrame :: The frame parameter for tables (STRING, 
 ;       default: topbot)
 
+; **** Plain Text
+;    asciiArt :: Use jave to convert images to ascii representations; 
+;       possible values: currently only jave (STRING, default: jave)
+
+;    imgAlt :: Fallback display name for images (STRING)
+
 
 ; *** Module
 ; **** Anyword
@@ -318,6 +404,8 @@
 
 ;    buttonsFileFormat :: The image suffix (STRING, default: png)
 
+;    buttonsHighlight :: Use a rollover effect (BOOLEAN, default: false)
+
 
 ; **** Obfuscate E-Mail
 ;    noObfuscatedNoscript :: If true, put only the name into the