UserManualTodo

HTML and PDF forms of the Larceny User Manual are being generated using AsciiDoc. We still need to work on DeveloperManualTodo.

The rest of this page is somewhat out of date, but records the history of our decision to go with AsciiDoc.

---

Jesse and PnkFelix realized as they were writing the "new" documentation for the 0.91 release that Larceny needs a real user manual, documenting the details of non-standard procedures (e.g. environment-copy).

• Of couse, there already is a user manual online

  • at: http://www.ccs.neu.edu/home/will/Larceny/manual/index.html
  • But perhaps that should be made the basis of a more thorough document?
  • It definitely needs to be updated; it appears to be specifically about the sparc native system.
  • Also, shouldn't we consider at least shipping the manual with the distribution?
  • At the very least, the manual (in some base form) should be put under version control
    • it is, see
    • source:/trunk/larceny_doc
    • source:/branches/larceny/larceny_doc
    • source:/trunk/larceny_old_notes
    • source:/branches/lth/larceny_old_notes
    • dude PnkFelix wishes he had know about these "old notes" before. There's a lot of info (historical and otherwise) tucked away in there!
      • source:/trunk/larceny_old_notes/24:final.tex is particularly interesting.
      • Ryan, Dale, PnkFelix, and Jesse should probably get together and try to document the history post Lars...
      • however, it doesn't belong in a manual. The wiki would certainly suffice for historical documentation.

• WillClinger says we should stick with HTML

  • We've already got a manual in place that's written in HTML
  • PnkFelix wants a nice PDF to look at, and doesn't know if HTML will give us that.

• AlecHeller recommended docbook to PnkFelix

  • (this was the, as he put it, "100%" solution)
  • if we go this route, he recommends using nxml-mode in emacs
  • he also mentioned MultiMarkdown.
    Probably not appropriate for this, as much as I'm coming to appreciate Markdown.

• LarsHansen says:

  • you could go with XHTML strict and CSS, and then use a tool like PrinceXML (http://www.princexml.com) to convert it to PDF. Web-readable formats rule.
  • (PnkFelix: "but that's not free...")