DocumentingAscend
From ASCEND
Contents |
[edit] User manuals
The user manuals (tutorial, language reference, GUI reference) are currently being converted from FrameMaker to Lyx. Lyx is an open source cross-platform structured-document editor, and really the only viable one with a simple GUI at present in the Linux world.
The current state of the LyX-based manual is here in the wiki at Media:book.pdf.
Currently most of the documentation has been converted but some of the converted files may be slightly out of date compared with the latest PDFs. We are working on getting this in shape as well as overcoming some issues with layout in Lyx: multiline table cells, captions for multi-page code listings, keyword index, and others.
If you are interested in helping with the documentation please see InstallingLyx. The files are all stored in the ASCEND code repository.
There is a simple FM-to-HTML conversion of the FrameMaker files at http://pye.dyndns.org/ascend/manual/
We plan to take this a little further and convert the files into HTML so that the documentation can then be exported to 'help file' formats and put in online form a la PHP.net documentation.
See also DesktopIntegration.
See also Solvers.
See also http://live.gnome.org/GnomeDocUtilsMigrationHowTo
[edit] Current conversion activities
All the chapters for the howTo documents are now converted to LyX. They are indexed and cross referenced. Still to be converted is the syntax document, which I am working on at this time. -- Main.ArthurWesterberg - 17 Jul 2006
[edit] Where are the documentation files?
The howTo manuals are in our subversion repository under http://ascendsvn.cheme.cmu.edu/ascend/code/branches/extfn/doc.
Old .pdf versions are on our web pages under documentation.
The current manual is at Media:book.pdf.
[edit] 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.
[edit] 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.
-- Main.ArthurWesterberg - 05 Jul 2006
[edit] 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-documents. 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)
[edit] Discussion?
Any change of a hosted version of the resulting dox? Ideally, you could set up a quick cron job to check out your sources and run doxygen on them, then stick them on this server somewhere?
