User Documentation Overhaul - Revision history

imported>Ladenberger: /* Description of Work and Progress */

2011-09-15T11:28:02Z

Description of Work and Progress

← Older revision		Revision as of 11:28, 15 September 2011
Line 17:		Line 17:
	We maintain a separate page [[Documentation Overhaul DoW]] that lists the Description of Work, Work Packages and their progress.		We maintain a separate page [[Documentation Overhaul DoW]] that lists the Description of Work, Work Packages and their progress.

	The current state of the documentation can be accessed from our Jenkins Server: http://~~www~~.~~stups.uni~~-~~duesseldorf~~.~~de/~jenkins/~~org~~.rodinp.handbook.feature/build/~~		The current state of the documentation can be accessed from our Jenkins Server: http://handbook.event-b.org

	== Plastex-Scripts on Sourceforge ==		== Plastex-Scripts on Sourceforge ==

imported>Jastram: Plastex performance

2011-07-12T07:23:31Z

Plastex performance

← Older revision		Revision as of 07:23, 12 July 2011
Line 74:		Line 74:
	At the Deploy Plenary meeting in Nice, we decided to implement the new help system using the plasTeX-approach.		At the Deploy Plenary meeting in Nice, we decided to implement the new help system using the plasTeX-approach.
	With this tool, we would generate HTML and Eclipse Help directly from LaTeX.		With this tool, we would generate HTML and Eclipse Help directly from LaTeX.

			== PlasTeX Performance ==

			With a version of dvipng before 1.14, plastex is slow and creates zombies while it runs. To fix this, you need to install dvipng 1.14. Here are the instructions for Ubuntu 11.04:

			* sudo apt-get install texinfo
			* sudo apt-get install libkpathsea-dev
			* sudo apt-get install libgd-dev
			* sudo apt-get install libgd2-xpm-dev
			* Download http://sourceforge.net/projects/dvipng/ and unpack it
			* ./configure
			* make
			* sudo make install

			That should do the trick. To check, run dvipng without arguments, it should print the version.

imported>Jastram at 07:07, 1 July 2011

2011-07-01T07:07:59Z

@@ Line 54: / Line 54: @@
 Extensions to Rodin will not be part of this effort (e.g. Decomposition).  Such efforts will continue to be documented in the Rodin Wiki.  However, we can include relevant references in the Rodin documentation.  This is mainly due to the fact that we have limited resources and must focus.
 == Wish List ==
@@ Line 84: / Line 73: @@
 At the Deploy Plenary meeting in Nice, we decided to implement the new help system using the plasTeX-approach.
-With this tool, we would generate HTML and Eclipse Help directly from LaTeX.  We realized a tiny portion of the documentation using this approach.  The following three resulting artifacts were all generated from the same LaTeX-sources:
+With this tool, we would generate HTML and Eclipse Help directly from LaTeX.

imported>Jastram: /* Description of Work and Progress */

2011-07-01T07:05:48Z

Description of Work and Progress

← Older revision		Revision as of 07:05, 1 July 2011
Line 16:		Line 16:

	We maintain a separate page [[Documentation Overhaul DoW]] that lists the Description of Work, Work Packages and their progress.		We maintain a separate page [[Documentation Overhaul DoW]] that lists the Description of Work, Work Packages and their progress.

			The current state of the documentation can be accessed from our Jenkins Server: http://www.stups.uni-duesseldorf.de/~jenkins/org.rodinp.handbook.feature/build/

	== Plastex-Scripts on Sourceforge ==		== Plastex-Scripts on Sourceforge ==

imported>Jastram at 13:34, 13 June 2011

2011-06-13T13:34:20Z

← Older revision		Revision as of 13:34, 13 June 2011
Line 16:		Line 16:

	We maintain a separate page [[Documentation Overhaul DoW]] that lists the Description of Work, Work Packages and their progress.		We maintain a separate page [[Documentation Overhaul DoW]] that lists the Description of Work, Work Packages and their progress.

			== Plastex-Scripts on Sourceforge ==

			The scripts for building the documentation and the latex are in Sourceforge at http://rodin-b-sharp.svn.sourceforge.net/viewvc/rodin-b-sharp/trunk/Handbook/

	== Requirements ==		== Requirements ==

imported>Jastram: /* plasTeX-based Solution */

2011-06-09T11:51:27Z

plasTeX-based Solution

← Older revision		Revision as of 11:51, 9 June 2011
Line 82:		Line 82:
	* [http://update.pror.org/rodin-doc/html/ HTML Documentation]		* [http://update.pror.org/rodin-doc/html/ HTML Documentation]
	* [http://update.pror.org/rodin-doc/rodin-doc.pdf Print Documentation (PDF)]		* [http://update.pror.org/rodin-doc/rodin-doc.pdf Print Documentation (PDF)]
	* [http://update.pror.org/rodin-doc/org.rodinp.~~help_1~~.~~0.0.201104261600.jar~~ Eclipse Help]: Please copy the plugin in the plugin-folder of any Eclipse-Installation. To access the Documentation, open the Help System (Help > Help Contents). You should see the entry "Rodin User Manual v.2.1.1" in the left pane.		* [http://update.pror.org/rodin-doc/org.rodinp.help.zip Eclipse Help]: Please copy the plugin in the plugin-folder of any Eclipse-Installation. To access the Documentation, open the Help System (Help > Help Contents). You should see the entry "Rodin User Manual v.2.1.1" in the left pane.

	== Comparing Solutions ==		== Comparing Solutions ==

imported>Jastram at 12:55, 2 June 2011

2011-06-02T12:55:23Z

← Older revision		Revision as of 12:55, 2 June 2011
Line 12:		Line 12:

	If you would like to stay informed about this project, please subscribe to our [http://lists.sourceforge.net/mailman/listinfo/rodin-b-sharp-handbook mailinglist].		If you would like to stay informed about this project, please subscribe to our [http://lists.sourceforge.net/mailman/listinfo/rodin-b-sharp-handbook mailinglist].

			== Description of Work and Progress ==

			We maintain a separate page [[Documentation Overhaul DoW]] that lists the Description of Work, Work Packages and their progress.

	== Requirements ==		== Requirements ==

imported>Jastram at 16:43, 30 May 2011

2011-05-30T16:43:20Z

← Older revision		Revision as of 16:43, 30 May 2011
Line 8:		Line 8:

	'''Minimize the access to an expert a user of Event-B/Rodin needs to be productive.'''		'''Minimize the access to an expert a user of Event-B/Rodin needs to be productive.'''

			== Mailinglist ==

			If you would like to stay informed about this project, please subscribe to our [http://lists.sourceforge.net/mailman/listinfo/rodin-b-sharp-handbook mailinglist].

	== Requirements ==		== Requirements ==

imported>Jastram at 16:17, 30 May 2011

2011-05-30T16:17:25Z

← Older revision		Revision as of 16:17, 30 May 2011
Line 9:		Line 9:
	'''Minimize the access to an expert a user of Event-B/Rodin needs to be productive.'''		'''Minimize the access to an expert a user of Event-B/Rodin needs to be productive.'''

	== ~~Approach~~ ==		== Requirements ==

	By talking to a number of Rodin users we found the following requirements:		By talking to a number of Rodin users we found the following requirements:
Line 36:		Line 36:

	Last, every version of Rodin has its own help system, consisting of a "snapshot" of a subset of the wiki. A script transforms the content to the Eclipse Help System.		Last, every version of Rodin has its own help system, consisting of a "snapshot" of a subset of the wiki. A script transforms the content to the Eclipse Help System.

	~~== Versioning ==~~

	The wiki always contains the latest version of the documentation. This presumably covers the latest version of Rodin. There is no easy way to browse an older version of the documentation online. However, this information is accessible through the Eclipse Help System of the corresponding Rodin Version.

	== Rodin Extensions ==		== Rodin Extensions ==
Line 73:		Line 69:
	== plasTeX-based Solution ==		== plasTeX-based Solution ==

	~~One possible solution~~ would ~~be to~~ generate HTML and Eclipse Help directly from LaTeX~~. This can be done with plasTeX~~. We realized a tiny portion of the documentation using this approach. The following three resulting ~~artefacts~~ were all generated from the same LaTeX-sources:		At the Deploy Plenary meeting in Nice, we decided to implement the new help system using the plasTeX-approach.
			With this tool, we would generate HTML and Eclipse Help directly from LaTeX. We realized a tiny portion of the documentation using this approach. The following three resulting artifacts were all generated from the same LaTeX-sources:

	* [http://update.pror.org/rodin-doc/html/ HTML Documentation]		* [http://update.pror.org/rodin-doc/html/ HTML Documentation]
	* [http://update.pror.org/rodin-doc/rodin-doc.pdf Print Documentation (PDF)]		* [http://update.pror.org/rodin-doc/rodin-doc.pdf Print Documentation (PDF)]
	* [http://update.pror.org/rodin-doc/org.rodinp.help_1.0.0.201104261600.jar Eclipse Help]: Please copy the plugin in the plugin-folder of any Eclipse-Installation. To access the Documentation, open the Help System (Help > Help Contents). You should see the entry "Rodin User Manual v.2.1.1" in the left pane.		* [http://update.pror.org/rodin-doc/org.rodinp.help_1.0.0.201104261600.jar Eclipse Help]: Please copy the plugin in the plugin-folder of any Eclipse-Installation. To access the Documentation, open the Help System (Help > Help Contents). You should see the entry "Rodin User Manual v.2.1.1" in the left pane.

	:
	: ''It may be possible to add a plasTeX renderer to output mediawiki. It looks like [https://github.com/nibrahim/PlasTeX/blob/master/plasTeX/Renderers/MediaWiki.py someone already gives a first stab at it] — to be investigated.'' [[User:Mathieu\|mathieu]] 14:00, 12 April 2011 (UTC)

	~~== pandoc based solution ==~~

	~~[http://johnmacfarlane.net/pandoc/ pandoc] advertises a latex to mediawiki conversion — to be investigated. [[User:Mathieu\|mathieu]] 14:06, 12 April 2011 (UTC)~~

	== Comparing Solutions ==		== Comparing Solutions ==

	~~The most promising approaches are~~ Wiki ~~(current~~ approach~~) and plasTex. In~~ the ~~following table, we try to compare them~~.		While we decided to use the plasTeX-approach, we left this table here for reference, comparing the current Wiki-approach with the plasTeX-solution.

	'''Note:''' We are only talking about the user documentation (less than 20 wiki pages). We are not suggesting to migrate plugin or developer documentation away from the wiki.		'''Note:''' We are only talking about the user documentation (less than 20 wiki pages). We are not suggesting to migrate plugin or developer documentation away from the wiki.

imported>Jastram: /* Possible Solution and Current State of Documentation */

2011-05-30T16:13:28Z

Possible Solution and Current State of Documentation

← Older revision		Revision as of 16:13, 30 May 2011
Line 17:		Line 17:
	# Find specific information.		# Find specific information.

	== ~~Possible Solution~~ and Current State of Documentation ==		== Approach and Current State of Documentation ==

	The above ~~can~~ be achieved by:		The above will be achieved by:

	# Providing a Tutorial that covers the essential aspects of Event-B and Rodin.		# Providing a Tutorial that covers the essential aspects of Event-B and Rodin.