Documentation systems - Revision history

Jpye: /* Source code documentation */

2012-02-02T22:39:54Z

Source code documentation

← Older revision		Revision as of 22:39, 2 February 2012
Line 49:		Line 49:
	Source code documentation for the <tt>base/generic</tt> parts of ASCEND (the compiler and solver, plus associated routines, but not the GUI) has been processed using [http://www.stack.nl/~dimitri/doxygen/ Doxygen] and is available online at		Source code documentation for the <tt>base/generic</tt> parts of ASCEND (the compiler and solver, plus associated routines, but not the GUI) has been processed using [http://www.stack.nl/~dimitri/doxygen/ Doxygen] and is available online at

	* http://~~ascend~~.~~cheme~~.~~cmu.edu~~/doxy/		* http://www.ascend4.org/doxy/

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

Jpye: /* Source code documentation */

2011-01-25T03:38:57Z

Source code documentation

← Older revision		Revision as of 03:38, 25 January 2011
Line 49:		Line 49:
	Source code documentation for the <tt>base/generic</tt> parts of ASCEND (the compiler and solver, plus associated routines, but not the GUI) has been processed using [http://www.stack.nl/~dimitri/doxygen/ Doxygen] and is available online at		Source code documentation for the <tt>base/generic</tt> parts of ASCEND (the compiler and solver, plus associated routines, but not the GUI) has been processed using [http://www.stack.nl/~dimitri/doxygen/ Doxygen] and is available online at

	* [http://ascend.cheme.cmu.edu/~~dox~~/]		* http://ascend.cheme.cmu.edu/doxy/

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

Jpye at 03:38, 25 January 2011

2011-01-25T03:38:40Z

← Older revision		Revision as of 03:38, 25 January 2011
Line 1:		Line 1:
	This page describes the systems we have in place for generating and maintaining ASCEND documentation.		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 ==		== User manual ==
	~~{{task}}~~

	~~''As of Oct 2009, the user documentation is increasingly being migrated to the wiki. Future status of the LyX-based documentation needs to be discussed.''~~

	The user manual is maintained as a series of linked [http://www.lyx.org 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.		The user manual is maintained as a series of linked [http://www.lyx.org 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.
Line 15:		Line 16:

	See also		See also

	* [http://live.gnome.org/GnomeDocUtilsMigrationHowTo]		* [http://live.gnome.org/GnomeDocUtilsMigrationHowTo]
	* [[Installing LyX]]		* [[Installing LyX]]

			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 ====		==== Some helpful LyX hints - maybe ====

Jpye at 23:00, 24 January 2011

2011-01-24T23:00:48Z

← Older revision		Revision as of 23:00, 24 January 2011
Line 1:		Line 1:
	This page describes the systems we have in place for generating and maintaining ASCEND documentation.		This page describes the systems we have in place for generating and maintaining ASCEND documentation.



	== User manual ==		== User manual ==
Line 17:		Line 15:

	See also		See also



	* [http://live.gnome.org/GnomeDocUtilsMigrationHowTo]		* [http://live.gnome.org/GnomeDocUtilsMigrationHowTo]
Line 26:		Line 22:

	* 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.		* 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.		* 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.		* 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.		* 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.		* 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).		* 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.		* 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.		* 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		* 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
	~~<pre>~~ * fig:atoms.taxonomy		** fig:atoms.taxonomy
	* eqn:dimeqns.lnPsat		** eqn:dimeqns.lnPsat
	* tab:model1.variables[[VesselModel]]		** tab:model1.variables[[VesselModel]]
	~~</pre>~~

	* 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.		* 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.

Line 56:		Line 42:

	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.		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 ==

	Source code documentation for the <tt>base/generic</tt> parts of ASCEND (the compiler and solver, plus associated routines, but not the GUI) has been processed using [http://www.stack.nl/~dimitri/doxygen/ Doxygen] and is available online at		Source code documentation for the <tt>base/generic</tt> parts of ASCEND (the compiler and solver, plus associated routines, but not the GUI) has been processed using [http://www.stack.nl/~dimitri/doxygen/ Doxygen] and is available online at



	* [http://ascend.cheme.cmu.edu/dox/]		* [http://ascend.cheme.cmu.edu/dox/]
Line 68:		Line 51:
	You can also generate your own local copy of this documentation by typing <tt>scons docs</tt> from the top directory in the source distribution.		You can also generate your own local copy of this documentation by typing <tt>scons docs</tt> 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:		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)		* complete documentation of undocumented modules (see '@todo' comments in source code)
	* clean up redundant comments left in place during initial rework		* clean up redundant comments left in place during initial rework
	~~<pre>~~ * remove original comments if new ones are acceptable		* remove original comments if new ones are acceptable
	* remove commented-out parameter and return value specifications (redundant with full function prototypes now in place)		* remove commented-out parameter and return value specifications (redundant with full function prototypes now in place)

	~~</pre>~~

	== Developer's manual ==		== Developer's manual ==
Line 82:		Line 61:
	The [[Developer%27s_Manual\|Developer's Manual]] is maintained in this wiki.		The [[Developer%27s_Manual\|Developer's Manual]] is maintained in this wiki.




	~~[[Category:Proposed]]~~
	[[Category:Development]]		[[Category:Development]]
	[[Category:Documentation]]		[[Category:Documentation]]

Jpye at 03:13, 19 May 2010

2010-05-19T03:13:48Z

← Older revision		Revision as of 03:13, 19 May 2010
Line 21:		Line 21:

	* [http://live.gnome.org/GnomeDocUtilsMigrationHowTo]		* [http://live.gnome.org/GnomeDocUtilsMigrationHowTo]
	* [[~~InstallingLyx~~]]		* [[Installing LyX]]

	==== Some helpful LyX hints - maybe ====		==== Some helpful LyX hints - maybe ====

UploadBot: Restored page from Google Cache, uploaded by John Pye

2010-05-13T13:29:49Z

Restored page from Google Cache, uploaded by John Pye

New page

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

== User manual ==
{{task}}

''As of Oct 2009, the user documentation is increasingly being migrated to the wiki. Future status of the LyX-based documentation needs to be discussed.''

The user manual is maintained as a series of linked [http://www.lyx.org 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 [[VersionManagement|code repository]], see {{srcdir|doc}}.

The most up-to-date user manual is usually available from the [[Category:Documentation]] 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

* [http://live.gnome.org/GnomeDocUtilsMigrationHowTo]
* [[InstallingLyx]]

==== 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
<pre> * fig:atoms.taxonomy
* eqn:dimeqns.lnPsat
* tab:model1.variables[[VesselModel]]
</pre>

* 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 <tt>base/generic</tt> parts of ASCEND (the compiler and solver, plus associated routines, but not the GUI) has been processed using [http://www.stack.nl/~dimitri/doxygen/ Doxygen] and is available online at

* [http://ascend.cheme.cmu.edu/dox/]

You can also generate your own local copy of this documentation by typing <tt>scons docs</tt> 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
<pre> * remove original comments if new ones are acceptable
* remove commented-out parameter and return value specifications (redundant with full function prototypes now in place)

</pre>

== Developer's manual ==

The [[Developer%27s_Manual|Developer's Manual]] is maintained in this wiki.

[[Category:Proposed]]
[[Category:Development]]
[[Category:Documentation]]