Commits

Brian Mearns  committed 3e957f9

Finished compat.txt doc.

  • Participants
  • Parent commits 1a74817

Comments (0)

Files changed (2)

-CURRENT
+Rel 3 - CURRENT
     [n] Added support for part- and book- title pages to EPUB output
         writer. (multiple cs, primarily the "epub parts and books"
         branch).
     [n] Added html-esc templ function to EPUB writer, to escape a string for
         HTML. (cs 60d7f4a76f2c)
 
-v1.1.0.0 - 2013-01-25
+Rel 2 - v1.1.0.0 - 2013-01-25
     [n] Added processing of license related meta values for EPUB, to add
         custom links and notices for licenses.  (cs 6a97be950984)
     [n] Added roman-up and roman-low templ functions for EPUB format.
     [s] Added some basic documentation in docs\intro.tome and
         doc\example.tome.  (multiple cs)
 
-v1.0.0.0 - 2013-01-24
+Rel 1 - v1.0.0.0 - 2013-01-24
     *Initial public release.
 
 

File doc/compat.txt

+
 
               The Tome Version Numbering and Compatibility Plan
 
 
+
+                         Overview of Version Numbers
+
 Tome uses a 4 part version number, with each part corresponding to a
 particular class of changes, and in general correspond to a specific level of
 compatibility.
 code, or something similar. You aren't likely to see changes to the semantic
 version very often, because they usually don't justify a new release.
 
-**What makes up the interface?
 
-**How to read the CHANGES file?
+
+                              The Release Number
+
+In addition to the version number, each official release is given an
+incremental release number. This makes it easy to see how many releases you've
+missed, since that is not apparent from the version number. The release
+numbers start at 1 and increment by 1 with each release.
+
+
+
+                               The CHANGES File
+
+The CHANGES.txt file at the top level of the source package describes the
+significant changes of each released version. The file is divided by release,
+with the first line of each section specifying the release number, the version
+number, and the release date. Following this is a list of the changes for that
+release. Each item starts with an indicator of what type of change is what:
+Major (M), minor (n), patch (p), or semantic (s). Then there's a description
+of the change, and lastly is an indication of what mercurial changesets are
+relevant to the change (abbreviated "cs"). If there are a large number of
+changesets, they will not all be listed; sometimes a branch name will be
+specified.
+
+
+
+                          What Defines the Interface
+
+Since all the version numbers are defined based on how they affect the
+interface, it's worth mentioning what is is included in the interface.
+
+There are several aspects which we count among the program's interface. The
+first is the arguments and options to the command line programs. Then there's
+the actual programming interface to the python modules (the API). Lastly,
+there are the template iterfaces. This is the interface for the templates that
+some of the output writers use and includes user-supplied template and
+resource files as well as templ variables or functions that are predefined by
+tome before processing the templates.
+
+What are not (currently) included in the interface are the specifics of the
+generated output. In other words, do not assume that specific files will be
+created or that you can parse the output consistently, beyond what is defined
+for the specific output medium (e.g., if the output writer generates an XHTML
+document, then it can be parsed as XHTML, but do not assume that Tome specific
+elements will obey a specific interface). Also note that for HTML based output
+(such as EPUB) the classes and ids that are used for each element follow
+general guidelines, but we do not attempt to hold these to an interface (at
+least not yet).
+
+Also not included in the interface is the XML output format for a tome
+document. This format has its own version number which uses the same scheme,
+but it is versioned separately from the tome package.