Documentation systems

From ASCEND
Jump to: navigation, search

This page describes the systems we have in place for generating and maintaining ASCEND documentation.

This Wiki

This wiki is the primary place where documentation is evolving for ASCEND. Discussions of soon-to-be-implemented features occur here, in parallel with email- and mailing-list-based discussions.

User manual

The user manual is maintained as a series of linked LyX documents. LyX is a GUI-based structured document editor that can generated Latex and PDF outputs, among others. Our original FrameMaker documentation was converted to this format in ~Jul 2006.

User manual source files are in our code repository, see doc.

The most up-to-date user manual is usually available from the page.

Eventually we would like to be able to export the user manual in the form of HTML suitable for generation of platform-specific help files such as 'CHM' files on Windows, and the Mac and Linux (LibRarian) equivalents.

See also

It should be noted that much of the documentation generated with LyX relates in general to the ASCEND language and then more specifically to the older Tcl/Tk-based GUI. There is nothing written at this stage about the newer PyGTK GUI (other that what is on this wiki).

Some helpful LyX hints - maybe

  • You have to set the column widths for tables (highlight the column in the table and then open /Edit/Table Settings).  !LyX does set table widths and will generally produce tables that are too wide. Lyx will automatically use multiple lines inside table cells to accommodate the width you set.
  • To label an equation with a number, place a label (Insert/Label) inside the equation environment. This one got me for quite a while.
  • These files have a lot of margin notes. In LyX, you can create a margin note by using /Insert/Margin Note.
  • To convert single words to italics and/or bold, select the tool "ab" from tools set at the top.
  • The meta key (M-) seems to be Alt, at least on my computer.
  • To force a line break in a chapter title, insert the break as a C-Return (i.e., Control-Return).
  • Use /View/DVI to see how the final document should appear when printed (except for fonts). To see the impact of font selection, use /View/Postscript.
  • If you do not find /View/Postscript (it disappeared on me), you can recover it as follows. First find your !GSview executable (likely in C:\Program Files\Ghostgum\gsview). Mine is called gsview32.exe. In !LyX, find Preferences (/Edit/Preference in 1.3.7) or /Tools/Preferences in 1.4.1). Open Outputs/File formats/Postscript. Put the name of your !GSview executable into the Viewer slot (e.g., I put gsview32.exe into that slot), hit modify, apply and save. That should fix it.
  • I have put all Index Entries and Labels after the item so referenced. The naming scheme for a Label is "[fig | tab | cha | sec | ssec | sssec | eqn]:fileID.label" which aids then in finding a correct reference both in the current and in other chapters for a book (where sec = section, ssec = subsection, etc.). Example labels would be
    • fig:atoms.taxonomy
    • eqn:dimeqns.lnPsat
    • tab:model1.variablesVesselModel
  • To create a new multi-word index entry, highlight the words from the left to the right and then select Insert/Index Entry.  !LyX places the Idx tag at the point you leave the cursor after highlighting - so if you sweep from right to left, it appears before the word, not after. Of course you can also simple click on the tag and edit the keyword.

Playing with Miktex (a version of latex)

Under the start menu, open the Browse Package tool. You should find a very long list of packages available to add to latex. Those that you have installed on your computer have their installation date in the Installed on column. You may wish to change the repository it looks in to be over the internet using =tug.ctan.org= if you are in the US.

You can also get Miktex to Update to any new versions of packages that have become available. It will go over the internet to your selected repository to see what is new.

I have tried to install class definitions etc as supplied by others and that are not in this repository -and have totally failed. If anyone figures that out, remove this comment and replace it with instruction on how to do it.

Source code documentation

Source code documentation for the base/generic parts of ASCEND (the compiler and solver, plus associated routines, but not the GUI) has been processed using Doxygen and is available online at

You can also generate your own local copy of this documentation by typing scons docs from the top directory in the source distribution.

A little work still remains to get all files well-documented. Jerry noted on 30 Aug 2005:

  • complete documentation of undocumented modules (see '@todo' comments in source code)
  • clean up redundant comments left in place during initial rework
  • remove original comments if new ones are acceptable
  • remove commented-out parameter and return value specifications (redundant with full function prototypes now in place)

Developer's manual

The Developer's Manual is maintained in this wiki.