Re: Project documentation format

From: David Mertz, Ph_dot_D_dot_ <voting-project_at_gnosis_dot_cx>
Date: Fri Aug 01 2003 - 10:27:38 CDT

  I thought of HTML as well, since it is easier to learn than is LaTeX.
  But I believe that APT is easier still (look at the sample document I
  wrote in my last note, which is also easier to read in email). And
  HTML is one of the output targets of APT, so we can still web publish
  documents just by running:

- ----
java fr.pixware.apt.convert.Driver somedoc.html somedoc.apt
- ----

  (and make the print-ready one by using the target name 'somedoc.tex' or
  'somedoc.rtf').

  APT specifies explicit pagination using the ^L character (0x0C). But
  aptconvert will also paginate as needed by the document flow (in
  page-oriented formats like PDF, I think there are some command-line
  switches for page size, page numbering, and so on).

  You can also draw ASCII tables, specify inserted graphics, use
  numbered, definition, and unnumbered lists, and insert code literals.
  That seems like the basic set of document elements we need. You cannot
  do something like use columns, precisely change margings in the
  document, add shading, nest tables, specify smallcaps (or underline :-(
  ), write complex equations like in TeX, or other really typographic
  things. You can, however, specify arbitrary unicode characters as
  <<<\u1234>>> (same style as in Python).

  Btw. To Anand's comment. 'aptconvert' is written in Java not Python.
  But there is no need to look at the LGPL source code to <<use>> the
  tool (I never have). A document contributor simply has to understand
  the very simple formatting rules (and, I suppose, any needed
  command-line switches for the tool). Python's reStructuredText is
  still too developer oriented to tell a non-programmer to just run the
  conversion, and my own smart ASCII tools lack some of the desirable
  output formats as-is.

  Yours, David...

  P.S. I decided again to turn this note into valid APT (after first just
  writing as I felt was completely natural). The changes required:

  [[1]] Indent everything by at least one space (headings wouldn't be,
        but I didn't use any).

  [[2]] Put a couple unindented dashes before and after my sample
        command-line.

  [[3]] Change my instinctive *bold* to <<bold>>.

  [[4]] Turn my unicode codepoint example into an <<<inline literal>>>.

  In any case, I will assume responsibility for these kind of minor
  touchups in ASCII documents that other contributors provide.
Received on Fri, 01 Aug 2003 11:27:38 -0400

This archive was generated by hypermail 2.1.8 : Wed Aug 06 2003 - 12:50:26 CDT