Mercurial > forge
changeset 9978:2eb4e527e1be octave-forge
added full documentation sources
author | mmarzolla |
---|---|
date | Fri, 06 Apr 2012 10:01:00 +0000 |
parents | 5e8f985ee1c4 |
children | 9553a11c6402 |
files | main/queueing/Makefile main/queueing/doc/INSTALL main/queueing/doc/Makefile main/queueing/doc/README main/queueing/doc/installation.txi main/queueing/doc/markovchains.txi main/queueing/doc/queueing.html main/queueing/doc/queueing.pdf main/queueing/doc/queueing.texi main/queueing/doc/queueingnetworks.txi main/queueing/examples/Makefile main/queueing/examples/grabdemo.m |
diffstat | 12 files changed, 90 insertions(+), 271 deletions(-) [+] |
line wrap: on
line diff
--- a/main/queueing/Makefile Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/Makefile Fri Apr 06 10:01:00 2012 +0000 @@ -18,7 +18,7 @@ \rm -f doc/conf.texi echo "@set VERSION $(VERSIONNUM)" > doc/conf.texi echo "@set VERSIONDATE $(VERSIONDATE)" >> doc/conf.texi - echo "@set top_srcdir " `pwd` >> doc/conf.texi + echo "@c @set top_srcdir " `pwd` >> doc/conf.texi DESCRIPTION: DESCRIPTION.in cat DESCRIPTION.in | \ @@ -33,7 +33,7 @@ for d in $(SUBDIRS); do \ $(MAKE) -C $$d $(MAKECMDGOALS); \ done - \rm -r -f *~ $(DISTNAME).tar.gz $(DISTNAME).tar.gz.uue $(PROGNAME) + \rm -r -f *~ $(DISTNAME).tar.gz $(DISTNAME).tar.gz.uue $(PROGNAME) $(PROGNAME)-html.tar.gz $(PROGNAME)-html.tar.gz.uue $(PROGNAME)-html distclean: clean for d in $(SUBDIRS); do \
--- a/main/queueing/doc/INSTALL Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/doc/INSTALL Fri Apr 06 10:01:00 2012 +0000 @@ -1,4 +1,4 @@ -This file documents the installation procedure of the `queueing' +This file documents the installation procedure of the Octave `queueing' toolbox. `queueing' is free software; you can redistribute it and/or modify @@ -6,9 +6,9 @@ later, as published by the Free Software Foundation. Note: This file (`INSTALL') is automatically generated from - `doc/installation.txi' in the `queueing' sources. Do not modify - this document directly, as changes will be lost. Modify the source - `doc/installation.txi' instead. + `doc/installation.txi' in the `queueing' subversion sources. Do + not modify this document directly, as changes will be lost. Modify + the source `doc/installation.txi' instead. 1 Installing the queueing toolbox ********************************* @@ -21,12 +21,13 @@ `http://octave.sourceforge.net/queueing/' - The package Web page is + Additional information can be found at `http://www.moreno.marzolla.name/software/queueing/' If you have a recent version of GNU Octave and a network connection, -you can install `queueing' directly from the prompt using this command: +you can install `queueing' directly from Octave command prompt using +this command: octave:1> pkg install -forge queueing @@ -55,11 +56,11 @@ octave:1> pkg install -local queueing-1.1.0.tar.gz This will install `queueing' within your home directory, and the -package will be available to your user only. *Note:* Octave version +package will be available to your user only. Note that Octave version 3.2.3 as shipped with Ubuntu 10.04 seems to ignore `-local' and always tries to install the package on the system directory. - To remove `queueing' you can use + To remove `queueing' simply use octave:1> pkg uninstall queueing @@ -92,79 +93,7 @@ search path each time Octave is started, and you no longer need to specify the `-p' option on the command line. -1.3 Content of the source distribution -====================================== - -The source code of the latest version of the `queueing' package can be -found in the Subversion repository at the URL: - -`http://octave.svn.sourceforge.net/viewvc/octave/trunk/octave-forge/main/queueing/' - - The source distribution contains the following directories (some of -which are not included in the installation tarball): - -`doc/' - Documentation source. Most of the documentation is extracted from - the comment blocks of individual function files from the `inst/' - directory. - -`inst/' - This directory contains the m-files which implement the various - Queueing Network algorithms provided by `queueing'. As a - notational convention, the names of source files containing - functions for Queueing Networks start with the `qn' prefix; the - name of source files containing functions for Continuous-Time - Markov Chains (CTMSs) start with the `ctmc' prefix, and the names - of files containing functions for Discrete-Time Markov Chains - (DTMCs) start with the `dtmc' prefix. - -`test/' - This directory contains the test functions used to invoke all - tests on all function files. - -`scripts/' - This directory contains some utility scripts mostly from GNU - Octave, which extract the documentation from the - specially-formatted comments in the m-files. - -`examples/' - This directory contains examples which are automatically extracted - from the `demo' blocks of the function files. - -`devel/' - This directory contains function files which are either not working - properly, or need additional testing before they are moved to the - `inst/' directory. - - - The `queueing' package ships with a Makefile which can be used to -produce the documentation (in PDF and HTML format), and automatically -execute all function tests. Specifically, the following targets are -defined: - -`all' - Running `make' (or `make all') on the top-level directory builds - the programs used to extract the documentation from the comments - embedded in the m-files, and then produce the documentation in PDF - and HTML format (`doc/queueing.pdf' and `doc/queueing.html', - respectively). - -`check' - Running `make check' will execute all tests contained in the - m-files. If you modify the code of any function in the `inst/' - directory, you should run the tests to ensure that no errors have - been introduced. You are also encouraged to contribute new tests, - especially for functions which are not adequately validated. - -`clean' -`distclean' -`dist' - The `make clean', `make distclean' and `make dist' commands are - used to clean up the source directory and prepare the distribution - archive in compressed tar format. - - -1.4 Using the queueing toolbox +1.3 Using the queueing toolbox ============================== You can use all functions by simply invoking their name with the
--- a/main/queueing/doc/Makefile Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/doc/Makefile Fri Apr 06 10:01:00 2012 +0000 @@ -1,6 +1,6 @@ DOC=queueing CHAPTERS=$(patsubst %.txi,%.texi,$(wildcard *.txi)) -DISTFILES=README INSTALL $(DOC).pdf $(DOC).html +DISTFILES=README INSTALL $(DOC).pdf $(DOC).html $(DOC).texi $(CHAPTERS) $(wildcard demo_*.texi) .PHONY: clean dist @@ -26,17 +26,20 @@ $(DOC).info: $(DOC).texi $(CHAPTERS) -$(MAKEINFO) $< -%.texi: %.txi DOCSTRINGS +%.texi: %.txi DOCSTRINGS DEMOS ../scripts/munge-texi -d DOCSTRINGS < $< > $@ DOCSTRINGS: $(wildcard ../inst/*.m) (cd ../scripts; ./mkdoc ../inst) > DOCSTRINGS || \rm -f DOCSTRINGS +DEMOS: + octave -q grabdemo.m ../inst/ && touch DEMOS + dist: ln $(DISTFILES) ../`cat ../fname`/doc/ clean: - \rm -f *.fns *.pdf *.aux *.log *.dvi *.out *.info *.html *.ky *.tp *.toc *.vr *.cp *.fn *.pg *.op *.au *.aus *.cps x.log *~ DOCSTRINGS $(CHAPTERS) ../INSTALL + \rm -f *.fns *.pdf *.aux *.log *.dvi *.out *.info *.html *.ky *.tp *.toc *.vr *.cp *.fn *.pg *.op *.au *.aus *.cps x.log *~ DOCSTRINGS DEMOS $(CHAPTERS) ../INSTALL demo_*.texi distclean: clean
--- a/main/queueing/doc/README Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/doc/README Fri Apr 06 10:01:00 2012 +0000 @@ -10,47 +10,17 @@ models. Open, closed and mixed networks are supported, with single or multiple classes of customers. The queueing toolbox also provides functions for steady-state and transient analysis of Markov chains, as -well as fo single station queueing systems. +well as for single station queueing systems. The Web page of the queueing toolbox is http://www.moreno.marzolla.name/software/queueing/ -The latest version can be downloaded from Octave-forge +The latest version can be downloaded from Octave forge http://octave.sourceforge.net/ -This package requires GNU Octave; version 3.0.0 or later should work. -The package contains the following directories (note that some of -these are only available in the SVN repository, and are not included -in the tarball published on Octave-forge): - -inst/ - Contains the Octave m-scripts implementing all functions - provided by the queueing toolbox. - -doc/ - Contains the user documentation, which is automatically - generated from the texinfo strings embedded in the m-scripts. - -scripts/ - Contains some scripts used to extract documentation strings - from the m-files. The scripts here have been taken almost - verbatim from the GNU Octave distribution. - -examples/ - Contains demo functions which are automatically extracted from - the scripts included in the inst/ directory. The demo - functions are put in this directory so that they can be - embedded into the package documentation. - -test/ - Contains the script used to execute all tests embedded within - functions in the inst/ directory. - -devel/ - Contains scripts which are currently under development, and - therefore should not be used. +This package requires GNU Octave; version 3.2.3 or later should work. The Octave queueing toolbox is distributed under the terms of the GNU General Public License, version 3 or later. See the file COPYING for
--- a/main/queueing/doc/installation.txi Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/doc/installation.txi Fri Apr 06 10:01:00 2012 +0000 @@ -22,8 +22,8 @@ @ifset INSTALLONLY @include conf.texi -This file documents the installation procedure of the @code{queueing} -toolbox. +This file documents the installation procedure of the Octave +@code{queueing} toolbox. @code{queueing} is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 3 @@ -31,9 +31,9 @@ @quotation Note This file (@file{INSTALL}) is automatically generated from -@file{doc/installation.txi} in the @code{queueing} sources. Do not -modify this document directly, as changes will be lost. Modify the -source @file{doc/installation.txi} instead. +@file{doc/installation.txi} in the @code{queueing} subversion sources. +Do not modify this document directly, as changes will be lost. Modify +the source @file{doc/installation.txi} instead. @end quotation @end ifset @@ -44,7 +44,7 @@ @menu * Installation through Octave package management system:: * Manual installation:: -* Content of the source distribution:: +* Development sources:: * Using the queueing toolbox:: @end menu @@ -60,13 +60,13 @@ @url{http://octave.sourceforge.net/queueing/} -The package Web page is +Additional information can be found at @url{http://www.moreno.marzolla.name/software/queueing/} If you have a recent version of GNU Octave and a network connection, -you can install @code{queueing} directly from the prompt using this -command: +you can install @code{queueing} directly from Octave command prompt +using this command: @example octave:1> @kbd{pkg install -forge queueing} @@ -103,12 +103,11 @@ @end example This will install @code{queueing} within your home directory, and the -package will be available to your user only. @strong{Note:} Octave -version 3.2.3 as shipped with Ubuntu 10.04 seems to ignore -@code{-local} and always tries to install the package on the system -directory. +package will be available to your user only. Note that Octave version +3.2.3 as shipped with Ubuntu 10.04 seems to ignore @code{-local} and +always tries to install the package on the system directory. -To remove @code{queueing} you can use +To remove @code{queueing} simply use @example octave:1> @kbd{pkg uninstall queueing} @@ -159,17 +158,23 @@ @c @c -@node Content of the source distribution -@section Content of the source distribution +@ifclear INSTALLONLY +@node Development sources +@section Development sources -The source code of the latest version of the @code{queueing} -package can be found in the Subversion repository at the URL: +The source code of the @code{queueing} package can be found in the +Subversion repository at the URL: @url{http://octave.svn.sourceforge.net/viewvc/octave/trunk/octave-forge/main/queueing/} -The source distribution contains the following directories (some of -which are not included in the installation tarball): +The source distribution contains additional development files which +are not present in the installation tarball. This section briefly +describes the content of the source tree. This is only relevant for +developers who want to modify the code or documentation; normal users +of the @code{queueing} package don't need + +The source distribution contains the following directories: @table @file @item doc/ @@ -236,6 +241,8 @@ @end table +@end ifclear + @c @c @c
--- a/main/queueing/doc/markovchains.txi Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/doc/markovchains.txi Fri Apr 06 10:01:00 2012 +0000 @@ -205,7 +205,7 @@ @example @c @group -@verbatiminclude @value{top_srcdir}/examples/demo_1_dtmc.m +@verbatiminclude demo_1_dtmc.texi @c @end group @result{} 0.083333 0.125000 0.083333 0.125000 0.166667 0.125000 0.083333 0.125000 @@ -519,7 +519,7 @@ @example @group -@verbatiminclude @value{top_srcdir}/examples/demo_1_ctmc.m +@verbatiminclude demo_1_ctmc.texi @result{} q = 0.50000 0.50000 @end group @end example @@ -595,7 +595,7 @@ @example @group -@verbatiminclude @value{top_srcdir}/examples/demo_1_ctmc_exps.m +@verbatiminclude demo_1_ctmc_exps.texi @end group @end example @@ -611,7 +611,7 @@ @example @group -@verbatiminclude @value{top_srcdir}/examples/demo_1_ctmc_taexps.m +@verbatiminclude demo_1_ctmc_taexps.texi @end group @end example @@ -670,7 +670,7 @@ @example @group -@verbatiminclude @value{top_srcdir}/examples/demo_1_ctmc_mtta.m +@verbatiminclude demo_1_ctmc_mtta.texi @result{} t = 78.333 @end group @end example
--- a/main/queueing/doc/queueing.html Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/doc/queueing.html Fri Apr 06 10:01:00 2012 +0000 @@ -44,7 +44,7 @@ <ul> <li><a href="#Installation-through-Octave-package-management-system">2.1 Installation through Octave package management system</a> <li><a href="#Manual-installation">2.2 Manual installation</a> -<li><a href="#Content-of-the-source-distribution">2.3 Content of the source distribution</a> +<li><a href="#Development-sources">2.3 Development sources</a> <li><a href="#Using-the-queueing-toolbox">2.4 Using the queueing toolbox</a> </li></ul> <li><a name="toc_Getting-Started" href="#Getting-Started">3 Introduction and Getting Started</a> @@ -302,7 +302,7 @@ <ul class="menu"> <li><a accesskey="1" href="#Installation-through-Octave-package-management-system">Installation through Octave package management system</a> <li><a accesskey="2" href="#Manual-installation">Manual installation</a> -<li><a accesskey="3" href="#Content-of-the-source-distribution">Content of the source distribution</a> +<li><a accesskey="3" href="#Development-sources">Development sources</a> <li><a accesskey="4" href="#Using-the-queueing-toolbox">Using the queueing toolbox</a> </ul> @@ -321,13 +321,13 @@ <p><a href="http://octave.sourceforge.net/queueing/">http://octave.sourceforge.net/queueing/</a> - <p>The package Web page is + <p>Additional information can be found at <p><a href="http://www.moreno.marzolla.name/software/queueing/">http://www.moreno.marzolla.name/software/queueing/</a> <p>If you have a recent version of GNU Octave and a network connection, -you can install <code>queueing</code> directly from the prompt using this -command: +you can install <code>queueing</code> directly from Octave command prompt +using this command: <pre class="example"> octave:1> <kbd>pkg install -forge queueing</kbd> </pre> @@ -356,19 +356,18 @@ <pre class="example"> octave:1> <kbd>pkg install -local queueing-1.1.0.tar.gz</kbd> </pre> <p>This will install <code>queueing</code> within your home directory, and the -package will be available to your user only. <strong>Note:</strong> Octave -version 3.2.3 as shipped with Ubuntu 10.04 seems to ignore -<code>-local</code> and always tries to install the package on the system -directory. - - <p>To remove <code>queueing</code> you can use +package will be available to your user only. Note that Octave version +3.2.3 as shipped with Ubuntu 10.04 seems to ignore <code>-local</code> and +always tries to install the package on the system directory. + + <p>To remove <code>queueing</code> simply use <pre class="example"> octave:1> <kbd>pkg uninstall queueing</kbd> </pre> <div class="node"> <a name="Manual-installation"></a> <p><hr> -Next: <a rel="next" accesskey="n" href="#Content-of-the-source-distribution">Content of the source distribution</a>, +Next: <a rel="next" accesskey="n" href="#Development-sources">Development sources</a>, Previous: <a rel="previous" accesskey="p" href="#Installation-through-Octave-package-management-system">Installation through Octave package management system</a>, Up: <a rel="up" accesskey="u" href="#Installation">Installation</a> @@ -403,7 +402,7 @@ longer need to specify the <samp><span class="option">-p</span></samp> option on the command line. <div class="node"> -<a name="Content-of-the-source-distribution"></a> +<a name="Development-sources"></a> <p><hr> Next: <a rel="next" accesskey="n" href="#Using-the-queueing-toolbox">Using the queueing toolbox</a>, Previous: <a rel="previous" accesskey="p" href="#Manual-installation">Manual installation</a>, @@ -411,15 +410,20 @@ </div> -<h3 class="section">2.3 Content of the source distribution</h3> - -<p>The source code of the latest version of the <code>queueing</code> -package can be found in the Subversion repository at the URL: +<h3 class="section">2.3 Development sources</h3> + +<p>The source code of the <code>queueing</code> package can be found in the +Subversion repository at the URL: <p><a href="http://octave.svn.sourceforge.net/viewvc/octave/trunk/octave-forge/main/queueing/">http://octave.svn.sourceforge.net/viewvc/octave/trunk/octave-forge/main/queueing/</a> - <p>The source distribution contains the following directories (some of -which are not included in the installation tarball): + <p>The source distribution contains additional development files which +are not present in the installation tarball. This section briefly +describes the content of the source tree. This is only relevant for +developers who want to modify the code or documentation; normal users +of the <code>queueing</code> package don't need + + <p>The source distribution contains the following directories: <dl> <dt><samp><span class="file">doc/</span></samp><dd>Documentation source. Most of the documentation is extracted from the @@ -478,7 +482,7 @@ <div class="node"> <a name="Using-the-queueing-toolbox"></a> <p><hr> -Previous: <a rel="previous" accesskey="p" href="#Content-of-the-source-distribution">Content of the source distribution</a>, +Previous: <a rel="previous" accesskey="p" href="#Development-sources">Development sources</a>, Up: <a rel="up" accesskey="u" href="#Installation">Installation</a> </div>
--- a/main/queueing/doc/queueing.texi Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/doc/queueing.texi Fri Apr 06 10:01:00 2012 +0000 @@ -38,13 +38,13 @@ @strong{See also:} \args\. @end macro -@macro examplefile{file} -@example -@group -@verbatiminclude @value{top_srcdir}/examples/\file\ -@end group -@end example -@end macro +@c @macro examplefile{file} +@c @example +@c @group +@c @verbatiminclude @value{top_srcdir}/examples/\file\ +@c @end group +@c @end example +@c @end macro @ifinfo @format
--- a/main/queueing/doc/queueingnetworks.txi Fri Apr 06 07:44:33 2012 +0000 +++ b/main/queueing/doc/queueingnetworks.txi Fri Apr 06 10:01:00 2012 +0000 @@ -439,7 +439,7 @@ follows: @example -@verbatiminclude @value{top_srcdir}/examples/demo_1_qnsolve.m +@verbatiminclude demo_1_qnsolve.texi @end example @@ -606,7 +606,7 @@ @end iftex @example -@verbatiminclude @value{top_srcdir}/examples/demo_1_qnconvolution.m +@verbatiminclude demo_1_qnconvolution.texi @print{} k(1)=1 prob=0.17975 @print{} k(2)=2 prob=0.48404 @print{} k(3)=0 prob=0.52779 @@ -719,7 +719,7 @@ @noindent @strong{EXAMPLE} @example -@verbatiminclude @value{top_srcdir}/examples/demo_1_qnopensingle.m +@verbatiminclude demo_1_qnopensingle.texi @print{} R_s = 1.4062 @print{} N = 4.2186 @end example @@ -769,7 +769,7 @@ @noindent @strong{EXAMPLE} @example -@verbatiminclude @value{top_srcdir}/examples/demo_1_qnclosedsinglemva.m +@verbatiminclude demo_1_qnclosedsinglemva.texi @end example @@ -1088,7 +1088,7 @@ @noindent @strong{EXAMPLE} @example -@verbatiminclude @value{top_srcdir}/examples/demo_1_qnclosed.m +@verbatiminclude demo_1_qnclosed.texi @end example @DOCSTRING(qnopen) @@ -1175,7 +1175,7 @@ @noindent @strong{EXAMPLE} @example -@verbatiminclude @value{top_srcdir}/examples/demo_1_qnvisits.m +@verbatiminclude demo_1_qnvisits.texi @end example @subsection Other utility functions
--- a/main/queueing/examples/Makefile Fri Apr 06 07:44:33 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,18 +0,0 @@ -DISTFILES=grabdemo.m Makefile - -.PHONY: clean distclean check - -ALL: done - -done: - octave -q grabdemo.m && touch done - -dist: - ln $(DISTFILES) ../`cat ../fname`/examples/ - -clean: - \rm -f demo_*.m *~ done - -distclean: clean - -
--- a/main/queueing/examples/grabdemo.m Fri Apr 06 07:44:33 2012 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,76 +0,0 @@ -## Copyright (C) 2005, 2006, 2007 David Bateman -## Modifications Copyright (C) 2009 Moreno Marzolla -## -## This file is part of qnetworks. It is based on the fntests.m -## script included in GNU Octave. -## -## Octave is free software; you can redistribute it and/or modify it -## under the terms of the GNU General Public License as published by -## the Free Software Foundation; either version 3 of the License, or (at -## your option) any later version. -## -## Octave is distributed in the hope that it will be useful, but -## WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -## General Public License for more details. -## -## You should have received a copy of the GNU General Public License -## along with Octave; see the file COPYING. If not, see -## <http://www.gnu.org/licenses/>. - -clear all; - -global fundirs; - -if (nargin == 1) - xdir = argv(){1}; -else - xdir = "../inst/"; -endif - -srcdir = canonicalize_file_name (xdir); -fundirs = {srcdir}; - -function print_file_name (nm) - filler = repmat (".", 1, 55-length (nm)); - printf (" %s %s", nm, filler); -endfunction - -function y = hasdemo (f) - fid = fopen (f); - str = fscanf (fid, "%s"); - fclose (fid); - y = findstr (str, "%!demo"); -endfunction - -function dump_demo( fname, code, idx ) - if ( !idx) - return; - endif - printf("%d demos found\n", length(idx)-1 ); - for i=2:length(idx) - demoname = [ "demo_" num2str(i-1) "_" fname ]; - fid = fopen( demoname, "wt" ); - fprintf(fid,"%s",code(idx(i-1)+1:idx(i)-1)); - fclose(fid); - endfor -endfunction - -for j=1:length(fundirs) - d = fundirs{j}; - lst = dir (d); - for i = 1:length (lst) - nm = lst(i).name; - if ((length (nm) > 3 && strcmp (nm((end-2):end), ".cc")) - || (length (nm) > 2 && strcmp (nm((end-1):end), ".m"))) - f = fullfile (d, nm); - ## Only run if it contains %!demo - if (hasdemo (f)) - tmp = strrep (f, [srcdir, "/"], ""); - print_file_name (tmp); - [code, idx] = test (f, "grabdemo" ); - dump_demo( nm, code, idx ); - endif - endif - endfor -endfor