Permalink
Browse files

Cleanup.

	* Makefile.am: Correct dist-hook so that it works with distcheck.
	  Alter the `rpm' target to place generates RPM files into doc/web/archive.
	  Add a `bin-zip' target to create a .bin.zip file of the installed files.
	* doc/Makefile.am: Add EXTRA_DIST files; fix `html' target to generate
	  documentation under web/docs.
	* doc/web/index.html: Added; http://www.ndesk.org/Options page.
	*	doc/web/.gitignore, doc/web/archive/.gitignore: Added; ignore generated
	 	files and directories.
	*	doc/en/examples/.gitignore, lib/pkgconfig/.gitignore: Ignore generated
	 	files (from renames & added example programs).
  • Loading branch information...
1 parent bb140d5 commit fd5daf62c6ee60877bd5145af79fba57973b1bd7 @jonpryor jonpryor committed Jan 26, 2008
Showing with 230 additions and 6 deletions.
  1. +10 −2 Makefile.am
  2. +4 −2 doc/Makefile.am
  3. +2 −0 doc/en/examples/.gitignore
  4. +1 −0 doc/web/.gitignore
  5. +1 −0 doc/web/archive/.gitignore
  6. +210 −0 doc/web/index.html
  7. +2 −2 lib/pkgconfig/.gitignore
View
@@ -27,7 +27,9 @@ CSC = $(MCS)
all: $(nolibdir)/net2/NDesk.Options.dll $(nolibdir)/net3.5/NDesk.Options.dll
dist-hook:
- git-log > $(distdir)/ChangeLog
+ if [ -d $(srcdir)/.git ] ; then \
+ (cd $(srcdir) && git-log > $(distdir)/ChangeLog) ; \
+ fi
$(nolibdir)/net2/NDesk.Options.dll: $(OPTIONS_SRC)
-mkdir -p `dirname $@`
@@ -51,7 +53,13 @@ check: $(nobindir)/options-test.exe $(nobindir)/options-test-linq.exe
rpm:
cp $(DIST_ARCHIVES) /usr/src/packages/SOURCES/ndesk-options-0.1.0.tar.gz && \
rpmbuild -bb ndesk-options.spec && \
- cp /usr/src/packages/RPMS/noarch/$(distdir)*.rpm .
+ cp /usr/src/packages/RPMS/noarch/$(distdir)*.rpm doc/web/archive
+
+bin-zip:
+ -rm doc/web/archive/$(distdir).bin.zip
+ $(MAKE) prefix= DESTDIR=$(distdir).bin install && \
+ zip -r doc/web/archive/$(distdir).bin.zip $(distdir).bin && \
+ rm -Rf $(distdir).bin
CLEANFILES = \
$(nobindir)/options-test.exe \
View
@@ -74,6 +74,7 @@ update-delete: $(addprefix ../lib/ndesk-options/, $(ASSEMBLIES)) $(srcdir)/en/ex
done
EXTRA_DIST = \
+ $(srcdir)/doc-template.html \
$(srcdir)/ndesk-options-docs.source \
$(srcdir)/en/examples/context.cs \
$(srcdir)/en/examples/context.in \
@@ -85,7 +86,8 @@ EXTRA_DIST = \
$(srcdir)/en/examples/localization.in \
$(srcdir)/en/examples/localization.txt \
$(srcdir)/en/examples/locale/es/LC_MESSAGES/localization.mo \
- $(DOCUMENTATION)
+ $(DOCUMENTATION) \
+ $(srcdir)/web/index.html
CLEANFILES = \
ndesk-options-docs.zip \
@@ -98,7 +100,7 @@ edit:
monodoc --edit $(srcdir)/en
html: $(DOCUMENTATION)
- monodocs2html -template:doc-template.html -source:en -ext:html -dest:html
+ monodocs2html -template:doc-template.html -source:en -ext:html -dest:web/docs
clean:
-rm $(CLEANFILES)
@@ -5,3 +5,5 @@ greet.txt
localization.exe
localization.txt
NDesk.Options.dll
+subclass.exe
+subclass.txt
View
@@ -0,0 +1 @@
+docs
@@ -0,0 +1 @@
+ndesk-options-*
View
@@ -0,0 +1,210 @@
+<html>
+<head>
+ <title>NDesk.Options</title>
+ <link rel="stylesheet" href="/style.css" type="text/css" />
+ <style>
+ div.information {
+ float: right;
+ width: 15em;
+ border-color: #D3D3D3;
+ border-style: solid;
+ border-width: thin;
+ margin-left: 0.5em;
+ margin-top: 2em;
+ margin-bottom: 1em;
+ background-color: #f0f0df;
+ }
+ div.information p {
+ margin-top: 0;
+ margin-bottom: 0;
+ padding-top: 0.5em;
+ padding-bottom: 0.5em;
+ padding-left: 0.5em;
+ }
+ </style>
+</head>
+<body>
+
+<div class="information">
+ <p><a href="docs">NDesk.Options Documentation</a></p>
+ <p><a href="#releases">Downloads</a></p>
+ <p><a href="#background">Background</a></p>
+ <p><a href="#variants">Variants</a></p>
+ <p><a href="#distribution">Distribution</a></p>
+ <p><a href="#development">Development</a></p>
+ <p><a href="http://git.ndesk.org/?p=ndesk-options;a=summary"
+ >GIT Repository</a></p>
+</div>
+
+<h1>NDesk.Options</h1>
+
+<p>NDesk.Options is a callback-based program option parser for C#.</p>
+
+<h2 id="releases">NDesk.Options Releases</h2>
+
+<p>NDesk.Options has had the following releases (in reverse chronological
+order):</p>
+
+<blockquote>
+ <dl>
+ <dt><a href="archive/ndesk-options-0.1.0.tar.gz">NDesk.Options 0.1.0</a>
+ <a href="archive/ndesk-options-0.1.0.bin.zip">(ZIP)</a>
+ <a href="archive/ndesk-options-0.1.0-1.noarch.rpm">(RPM)</a></dt>
+ <dd><a href="http://www.jprl.com/Blog/archive/development/ndesk.options/2008/"
+ >Release Notes</a>.</dd>
+ <dt><a href="http://www.jprl.com/Blog/archive/development/mono/2008/Options.v1.cs"
+ >Original Options.cs Prototype</a></dt>
+ <dd><a href="http://www.jprl.com/Blog/archive/development/mono/2008/Jan-07.html"
+ >Announcement</a>.</dd>
+ </dl>
+</blockquote>
+
+<h2 id="features">Features</h2>
+
+<p><a href="docs/NDesk.Options/OptionSet.html">OptionSet</a> currently
+supports:</p>
+
+<ul>
+ <li><i>Boolean</i> options of the form: <tt>-flag</tt>, <tt>--flag</tt>,
+ and <tt>/flag</tt>. Boolean parameters can have a `<tt>+</tt>' or
+ `<tt>-</tt>' appended to explicitly enable or disable the flag (in
+ the same fashion as <tt>mcs -debug+</tt>).
+ For boolean callbacks, the provided value is non-<tt>null</tt> for enabled, and
+ <tt>null</tt> for disabled.</li>
+ <li><i>Value</i> options with a required value (append `<tt>=</tt>' to the
+ option name) or an optional value (append `<tt>:</tt>' to the option
+ name). The option value can either be in the current option
+ (<tt>--opt=value</tt>) or in the following parameter (<tt>--opt value</tt>).
+ The actual value is provided as the parameter to the callback
+ delegate, unless it's (1) optional and (2) missing, in which case
+ <tt>null</tt> is passed.</li>
+ <li><i>Bundled</i> parameters which <i>must</i> start with a single `<tt>-</tt>'
+ and consists of only single characters. In this manner, <tt>-abc</tt>
+ would be a shorthand for <tt>-a -b -c</tt>.</li>
+ <li>Option processing is disabled when <tt>--</tt> is encountered.</li>
+</ul>
+
+<h2 id="background">Background</h2>
+
+<p>I had been doing a lot of work on
+<a href="http://www.mono-project.com/Monodocer">monodocer</a>,
+and the warning about
+<a href="http://www.go-mono.com/docs/index.aspx?tlink=0@N%3aMono.GetOptions"
+>Mono.GetOptions</a> being obsolete was getting annoying. So after
+killing an afternoon coming up with a similar reflection-based alternative, it
+dawned on me that (1) any such alternative would <i>not</i> be "simple", and
+(2) <i>using</i> such a library would have a
+<a href="http://www.codinghorror.com/blog/archives/001025.html">high code
+overhead</a>. After thinking back on the previous option parsing libraries
+I've used, I remembered Perl's
+<a href="http://perldoc.perl.org/Getopt/Long.html">Getopt::Long</a> library,
+which permits short and concise declarations of the options a program
+supports.</p>
+
+<p>The result: a cunning use of C# 3.0 collection initializers and lambda
+delegates:</p>
+
+<blockquote><pre class="code-csharp">
+string data = null;
+bool help = false;
+int verbose = 0;
+
+var p = new OptionSet () {
+ { "file=", v =&gt; data = v },
+ { "v|verbose", v =&gt; { ++verbose } },
+ { "h|?|help", v =&gt; help = v != null },
+};
+List&lt;string&gt; extra = p.Parse (args);</pre>
+</blockquote>
+
+<p>C# 3.0 features are not required, and <tt>OptionSet</tt> can be used with
+C# 2.0:</p>
+
+<blockquote><pre class="code-csharp">
+string data = null;
+bool help = false;
+int verbose = 0;
+
+OptionSet p = new OptionSet ()
+ .Add ("v|verbose", delegate (string v) { if (v != null) ++verbose; })
+ .Add ("h|?|help", delegate (string v) { show_help = v != null; })
+ .Add ("n|name=", delegate (string v) { names.Add (v); });
+List&lt;string&gt; extra = p.Parse (args);</pre>
+</blockquote>
+
+<p>The <a href="docs">documentation</a>
+<a href="docs/NDesk.Options/OptionSet.html">has</a>
+<a href="docs/NDesk.Options/OptionSet.html#C:NDesk.Options.OptionSet(System.Converter{System.String,System.String})">more</a>
+<a href="docs/NDesk.Options/OptionSet.html#M:NDesk.Options.OptionSet.Add%60%601(System.String,System.String,System.Action{%60%600,NDesk.Options.OptionContext})">examples</a>.
+</p>
+
+<h2 id="variants">Variants</h2>
+
+<p>In order to cut down on the number of unique types (and the combinatorial
+explosion that produces when trying to mix-and-match delegate types),
+NDesk.Options "uses" some .NET 3.5 types.</p>
+
+<p>Normally, this would prevent .NET 2.0 support.</p>
+
+<p>So to support both .NET 2.0 and .NET 3.5, NDesk.Options can be built in two
+separate ways:</p>
+
+<ul>
+ <li>With <tt>LINQ</tt> <tt>#define</tt>d: .NET 3.5 is assumed.</li>
+ <li>With <tt>LINQ</tt> <tt>#undef</tt>ined: .NET 2.0 is assumed.</li>
+</ul>
+
+<p>When <tt>LINQ</tt> is not defined, the
+<a href="docs/System/Action`2.html">System.Action&lt;T1,T2&gt;</a> delegate
+type is present within <tt>NDesk.Options.dll</tt>. Consequently, to prevent
+ambiguous type errors, you should only use the <tt>LINQ</tt> version on
+.NET 3.5, and the non-<tt>LINQ</tt> version on .NET 2.0.
+
+<h2 id="distribution">Distribution</h2>
+
+<p>In accordance with the
+<a href="http://www.mono-project.com/Guidelines:Application_Deployment#Libraries_with_Unstable_APIs"
+>Guidelines for Application Deployment</a>, there are <tt>pkg-config</tt>
+files to permit simple access to the source or pre-compiled assemblies for
+re-use.</p>
+
+<p>There are three ways to use NDesk.Options</p>
+
+<ul>
+ <li>Bundle <tt>src/NDesk.Options/NDesk.Options/Options.cs</tt> with your app.
+ You should <tt>#define LINQ</tt> as appropriate, depending on whether you
+ target .NET 2.0 or .NET 3.5 (as <a href="#variants">described above</a>).
+ Source is readily obtained via:
+ <blockquote>
+ <tt>pkg-config --variable=Sources ndesk-options</tt>
+ </blockquote>
+ <p><tt>Options.cs</tt> is also present within the <tt>.bin.zip</tt> file, as
+ <tt>ndesk-options-<i>VERSION</i>.bin/lib/ndesk-options/Options.cs</tt>.</p>
+ </li>
+ <li>Use the .NET 2.0-specific <tt>NDesk.Options.dll</tt>:
+ <blockquote>
+ <tt>pkg-config --variable=Libraries ndesk-options</tt>
+ </blockquote>
+ <p><tt>NDesk.Options.dll</tt> is also present within the <tt>.bin.zip</tt>
+ file, as <tt>ndesk-options-<i>VERSION</i>.bin/lib/net2/NDesk.Options.dll</tt>.</p>
+ </li>
+ <li>Use the .NET 3.5-specific <tt>NDesk.Options.dll</tt>:
+ <blockquote>
+ <tt>pkg-config --variable=Libraries ndesk-options-linq</tt>
+ </blockquote>
+ <p><tt>NDesk.Options.dll</tt> is also present within the <tt>.bin.zip</tt>
+ file, as <tt>ndesk-options-<i>VERSION</i>.bin/lib/net3.5/NDesk.Options.dll</tt>.</p>
+ </li>
+</ul>
+
+<h2 id="development">Development</h2>
+
+<p>A <a href="http://git.ndesk.org/?p=ndesk-options;a=summary">git
+repository</a> is available:</p>
+
+<blockquote>
+ <tt>git-clone git://git.ndesk.org/pub/scm/ndesk-options
+</blockquote>
+
+</body>
+</html>
@@ -1,2 +1,2 @@
-ndesk-options-net2.0.pc
-ndesk-options-net3.5.pc
+ndesk-options.pc
+ndesk-options-linq.pc

0 comments on commit fd5daf6

Please sign in to comment.