Geschreibsel Tagged: authoring http://fsteeg.com/tags/authoring Sun, 14 Mar 2010 00:00:01 +0000 Sun, 14 Mar 2010 00:00:01 +0000 Generating documentation from a wiki with Ant and Mylyn WikiText <p><small>Cross-posted to: <a href="https://fsteeg.wordpress.com/2010/03/14/generating-documentation-from-a-wiki-with-ant-and-mylyn-wikitext/">https://fsteeg.wordpress.com/2010/03/14/generating-documentation-from-a-wiki-with-ant-and-mylyn-wikitext/</a></small></p> <p/> I was planning to update the <a href="http://wiki.eclipse.org/Graphviz_DOT_as_a_DSL_for_Zest">dot4zest</a> documentation when I saw the recent posts by <a href="http://greensopinion.blogspot.com/2010/03/crowdsourcing-documentation-made-easy.html">David Green</a> and <a href="http://aniszczyk.org/2010/03/13/crowdsourcing-documentation-at-eclipse/">Chris Aniszczyk</a> on generating Eclipse help right from the wiki. <p/> Outdated and duplicated documentation is one of the topics I keep encountering in basically every project I work on. Given that I was already generating the dot4zest help with WikiText (but from a file, not straight from the wiki) I decided to give it a try. <p/> Following the instructions in the <a href="http://wiki.eclipse.org/DocumentationGuidelines/CrowdSourcingExample">crowdsourcing example</a>, I first got the WikiText <a href="http://www.eclipse.org/downloads/download.php?file=/tools/mylyn/update/weekly/mylyn-wikitext-standalone-latest.zip">standalone Jars</a> and set up a small Ant script: <pre><code>&lt;project name=&quot;dot4zest&quot; default=&quot;doc&quot; basedir=&quot;.&quot;&gt; wikitext.tasks.classpath&quot;&gt; &lt;fileset dir=&quot;Graphviz_DOT_as_a_DSL_for_Zest&quot;&gt; mylyn.wikitext.*core*.jar&quot;/&gt; &lt;/fileset&gt; &lt;/path&gt; &lt;taskdef classpathref=&quot;wikitext.tasks.classpath&quot; resource= &quot;org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties&quot;/&gt; &lt;taskdef classpathref=&quot;wikitext.tasks.classpath&quot; resource= &quot;org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties&quot;/&gt; &lt;target name=&quot;doc&quot;&gt; &lt;!-- Set up the base wiki location to pull content from: --&gt; &lt;mediawiki-to-eclipse-help wikiBaseUrl=&quot;http://wiki.eclipse.org&quot; validate=&quot;true&quot; failonvalidationerror=&quot;true&quot; prependImagePrefix=&quot;images&quot; formatoutput=&quot;true&quot; defaultAbsoluteLinkTarget=&quot;doc_external&quot; dest=&quot;${basedir}&quot; title=&quot;Graphviz DOT as a DSL for Zest&quot; generateUnifiedToc=&quot;false&quot;&gt; &lt;!-- Set up which wiki page to pull from: --&gt; &lt;path name=&quot;Graphviz_DOT_as_a_DSL_for_Zest&quot; title=&quot;Graphviz DOT as a DSL for Zest&quot; generateToc=&quot;true&quot;/&gt; &lt;/mediawiki-to-eclipse-help&gt; &lt;/target&gt; &lt;/project&gt;</code></pre> <p/> Running the Ant file (<em>ant</em> in a console or double-click after dragging it onto the Ant view in Eclipse) pulls the content <a href="http://wiki.eclipse.org/Graphviz_DOT_as_a_DSL_for_Zest">from the wiki location</a> specified in the script and generates the Eclipse help: <p/> <a href="http://fsteeg.com/images/dot4zest-eclipse-help-toc.png"><img class="alignnone size-full" title="dot4zest-eclipse-help-toc" src="http://fsteeg.com/images/dot4zest-eclipse-help-toc.png" alt="Generated Eclipse Help TOC" /></a> <p/> Next, I updated the help TOC extension in the plugin.xml: <pre><code>&lt;extension point=&quot;org.eclipse.help.toc&quot;&gt; &lt;toc file=&quot;Graphviz-DOT-as-a-DSL-for-Zest-toc.xml&quot; primary=&quot;true&quot;/&gt; &lt;/extension&gt;</code></pre> <p/> Then I added the generated help resources to the binary build in the <em>build</em> tab of the manifest editor to have them included in the deployed bundle: <p/> <a href="http://fsteeg.com/images/dot4zest-eclipse-help-build.png"><img class="alignnone size-full" title="dot4zest-eclipse-help-build" src="http://fsteeg.com/images/dot4zest-eclipse-help-build.png" alt="Including the generated help resources in the binary build" /></a> <p/> With this, the wiki page content is included in the Eclipse online help of the bundle (Help &gt; Help Contents). <p/> Being based on <a href="http://wiki.eclipse.org/Mylyn/WikiText">Mylyn WikiText</a> - which supports many wiki markup formats (textile, confluence, mediawiki, trac and twiki) as well as output to other formats than Eclipse help (e.g. DocBook and DITA) - I imagine this approach could be used in many project documentation setups. <p/> I really like this WikiText feature both for technical and collaborative reasons: it reduces duplication (<em>DRY for docs!</em>) and eases collaboration on documentation. Instead of being part of the code repository, the help content is made available to a wider range of editors than the people committing code - which I believe is useful for projects of any size.I was planning to update the dot4zest documentation when I saw the recent posts by David Green and Chris Aniszczyk on generating Eclipse help right from the wiki. [...] http://fsteeg.com/notes/generating-documentation-from-a-wiki-with-ant-and-mylyn-wikitexthttp://fsteeg.com/notes/generating-documentation-from-a-wiki-with-ant-and-mylyn-wikitext Sun, 14 Mar 2010 00:00:01 +0000 authoringprogrammingeclipsesoczest Plain-text, content-driven writing <p><small>Cross-posted to: <a href="https://fsteeg.wordpress.com/2007/07/28/plain-text-content-driven-writing/">https://fsteeg.wordpress.com/2007/07/28/plain-text-content-driven-writing/</a></small></p> <p/> I just got to share how happy I am with my (scientific) writing toolkit, which I would sum up as "plain-text, content-driven writing". It's plain text because I try to put as much <a href="http://www.pragmaticprogrammer.com/ppbook/extracts/rule_list.html">information in plain text</a> as possible. And using tools like LaTeX, Bibtex and <a href="http://www.graphviz.org/">Graphviz</a>, that is quite a lot. LaTeX does all the layouting of text, footnotes and stuff; it also has environments for tables, <a href="http://www.ctan.org/tex-archive/help/Catalogue/entries/barkom.html">bar charts</a>, <a href="http://www.ctan.org/tex-archive/macros/latex/contrib/algorithm2e/">algorithms</a>, glossaries, an index, <a href="http://www.ctan.org/tex-archive/macros/latex/contrib/listings/">source code</a>, <a href="http://www.ctan.org/tex-archive/fonts/tipa/">IPA signs</a>, and <a href="http://www.ctan.org/tex-archive/macros/latex/contrib/covington/">glossed examples</a>. Graphviz is excellent for all kinds of graphs, like trees or state machines. It also works quite well for UML <a href="http://wp.me/pwKJk-1H">class</a> and <a href="http://wp.me/pwKJk-1G">activity</a> diagrams. Both LaTeX and Graphviz are content-driven because when using them, you can focus on content and need not worry about layouting at all, leaving that to someone who knows how to do that well and fast (like, again, LaTeX, Bibtex and Graphviz). Then take this fully plain-text content and combine it with a <a href="http://subversion.tigris.org/">great versioning system</a>, add <a href="http://www.polarion.org/index.php?page=overview&amp;project=subversive">its integration</a> and <a href="http://wp.me/pwKJk-1L">Graphviz support</a> in your <a href="http://www.eclipse.org/">favourite IDE</a>, grab an <a href="http://www.uoregon.edu/%7Ekoch/texshop/">awesome LaTeX-Editor</a>, find a way to <a href="http://www.citeulike.org/">organize your literature</a> and you will, maybe, be as happy as I am. http://fsteeg.com/notes/plain-text-content-driven-writinghttp://fsteeg.com/notes/plain-text-content-driven-writing Sat, 28 Jul 2007 00:00:01 +0000 authoring Mac Apps <p><small>Cross-posted to: <a href="https://fsteeg.wordpress.com/2007/02/17/mac-apps/">https://fsteeg.wordpress.com/2007/02/17/mac-apps/</a></small></p> <p/> Alright, while I love my Mac and all I have noticed a relative unstableness in the apps I regularly use, probably caused by the two major switches of OS 9 to OS X and from PPC to Intel recently. I think the only Mac app I'm using from the very beginning of being a Mac user (which is since about 1999) is the fabulous MacSOUP. So when I need an app for a task I do less often (like an FTP-client) I'm lost and can't remember what that app to use is. So I decided to compile this list, mainly as a note to myself, it may act as a check list for setting up a fresh system... I've added a [commercial]-tag on the apps that are commercial, the rest is either FOSS or Freeware. First section is internet-related stuff: <ul> <li><a href="http://home.snafu.de/stk/macsoup/">MacSOUP</a> for news, a very effective, nicely key-controllable offline newsreader [commercial]</li> <li><a href="http://www.mozilla-europe.org/de/products/firefox/">Firefox</a> for the Web; I used to hesitate using Firefox over <a href="http://www.apple.com/de/macosx/features/safari/">Safari</a> but since I discovered the Firefox <a href="http://del.icio.us/help/firefox/extension">delicious extension</a> the only reason to stick to Safari -- which was the command-number commands to post a link to delicious -- is gone... well Safari renders more nicely and has build-in RSS support but crashes and is slow too often on the other hand</li> <li><a href="http://webkit.org/">Webkit</a> actually makes Safari the way it should be: really fast and supporting all the sites that trouble standard Safari</li> <li><a href="http://colloquy.info/">Colloquy</a> is a great IRC client, but the constant notices and bouncing in the dock (which couldn't be turned off completely even with using <a href="http://colloquy.info/project/wiki/Documentation/TipsAndTricks/HiddenPreferences">hidden options</a>) are just too annoying for me, so I switched to <a href="http://xchataqua.sourceforge.net/">XChat Aqua</a>, which is a lot less Mac-like but quiet at least, and seems very stable</li> <li><a href="http://transmission.m0k.org/">Transmission</a> is a great BitTorrent-Client, looks just like the download window in Safari, very nice and Mac-like</li> <li><a href="http://cyberduck.ch/">Cyberduck</a> is my favorite FTP/SCP client</li> <li><a href="http://www.adiumx.com/">Adium</a> is a nice multi-protocol IM client, and <a href="http://www.skype.com/">Skype</a> is there, too</li> <li><a href="http://www.redstonesoftware.com/products/vine/server/vineosx/index.html">OSXvnc</a> seems to be my choice for a VNC server, I don't seem to have a client installed currently, but I remember there was one with a funny name... I remember: <a href="http://sourceforge.net/projects/cotvnc/">Chicken of the VNC</a> (almost as weird as MacSOUP)</li> <li>I used to like <a href="http://www.carracho.com/">Carracho</a>, and sometimes I liked <a href="http://www.haxial.com/products/kdx/">KDX</a> too...</li> <li>Apple <a href="http://www.apple.com/macosx/features/mail/">Mail</a> only very rarely gave me reasons to complain</li> </ul> Next, something like an office-section, nothing complete again, just my personal collection, as stated above: <ul> <li>TeTeX ('tetex') from <a href="http://www.macports.org/">MacPorts</a> with <a href="http://www.uoregon.edu/%7Ekoch/texshop/texshop.html">TeXShop</a> as an editor for Word Processing</li> <li><a href="http://bibdesk.sourceforge.net/">BibDesk</a> seems like a nice desktop Bibtex app, but I usually use <a href="http://www.citeulike.org/">CiteULike</a>; same goes for <a href="http://www.scifihifi.com/cocoalicious/">Cocoalicious</a> and <a href="http://del.icio.us/">Delicious</a></li> <li>The Mac OS port (with awesome anti-aliasing through Apple's Quartz) of <a href="http://www.pixelglow.com/graphviz/">GraphViz</a> for auto-generated graphs</li> <li><a href="http://www.omnigroup.com/applications/omnigraffle/">OmniGraffle</a> for manually created diagrams, also great for handouts and posters [commercial]</li> <li><a href="http://seashore.sourceforge.net/">Seashore</a> (kind of a Gimp port) for image processing, I sometimes still use <a href="http://www.lemkesoft.de/">GraphicConverter</a>, but less and less; and <a href="http://www.inkscape.org/">Inkscape</a> for SVG</li> <li><a href="http://www.neooffice.org/">NeoOffice</a> (an OpenOffice port) for opening OpenOffice/Word-files and for spreadsheets and presentations</li> <li><a href="http://www.eclipse.org/">Eclipse</a> as an IDE for anything and nothing in particular, well for Java and Ruby mostly, and as a general-purpose text editor, which it become with installed line wrap plugin (see <a href="http://89.149.194.79:3000/notes/programming/Plugins">plugins note</a>). Eclipse is surprisingly annoying on the Mac if you are working with the Windows version from time to time; it's slow and crashes, -- certainly, most of the times it just works and rocks, but it could do better. An interesting development is SWT on Swing, used in the <a href="http://eos.sourceforge.net/">Eclipse on Swing</a> project. It's still buggy on the Mac, but that infamous occasional seconds-lasting pause for popup menus in the Mac version of Eclipse (with the Carbon-SWT) isn't there with the Swing version. Same goes for <a href="http://simplygenius.com/geekblog/2005/08/22/1124720745359.html">running under GTK</a> with X11 (both for increased performance and bugs). The eclipse.ini need some additional stuff like: -Xms40m -Xmx1024m -XX:MaxPermSize=128m</li> <li><a href="http://www.barebones.com/products/textwrangler/">TextWrangler</a> for the occasional look into some weird large file etc, most people seem to prefer <a href="http://macromates.com/">TextMate</a> as a small stand-alone editor [commercial]</li> <li><a href="http://iterm.sourceforge.net/">iTerm</a> as a tabbed terminal app</li> <li><a href="http://www.pgadmin.org/">pgAdmin</a> is a nice frontend for Postgres (which I <a href="http://developer.apple.com/internet/opensource/postgres.html">usually compile</a>), which never ever misbehaved</li> <li><a href="http://www.mamp.info/">MAMP</a> is my choice for an all-in-one web-dev package, it worked better for me with the new Intel machines than <a href="http://www.apachefriends.org/">XAMPP</a> (which wouldn't work with mod_rewrite support)</li> </ul> Then, lets call it media-related apps: <ul> <li><a href="http://www.apple.com/itunes/download/">iTunes</a> rocked ever since it was introduced (except for when it deleted your entire music collection)</li> <li><a href="http://www.rogueamoeba.com/audiohijackpro/">Audio Hijack Pro</a> is a great tool for capturing the output of a particular app, like for recording streamed audio [commercial]</li> <li><a href="http://www.elgato.com/index.php?file=products_whatiseyetv">EyeTV</a> is a great app for watching DVB-T and for editing and exporting, eg. for burning with <a href="http://www.roxio.com/enu/products/toast/titanium/overview.html">Toast</a> [both commercial]</li> <li><a href="http://handbrake.m0k.org/">HandBrake</a> is a DVD-Ripper (with one of those nice names again, a propos: an option here is <a href="http://www.mactheripper.org/">MacTheRipper</a>)</li> <li><a href="http://earth.google.de/download-earth.html">Google Earth</a> and <a href="http://maps.google.de/">Google Maps</a> for maps and satellite images</li> </ul> And finally system utils and stuff like that: <ul> <li><a href="http://www.manytricks.com/witch/">Witch</a> is the missing functionality for switching windows of an app, and is much more useful than Expose, IMO</li> <li>For the times I'm annoyed by the Finder, I use <a href="http://www.apple.com/downloads/macosx/system_disk_utilities/xfolders.html">XFolders</a> (GUI) or MC ('mc') via MacPorts (Terminal)</li> <li><a href="http://www.parallels.com/en/products/workstation/mac/">Parallels</a>, using the <a href="http://www.apple.com/macosx/bootcamp/">Bootcamp</a>-Partition gives a nice, flexible multi-OS system</li> <li><a href="http://www.derlien.com/">Disk Inventory X</a> shows disk usage, not sure how useful the app is yet, seems like I've settled with Finder+du/df in the terminal</li> <li>The most useful backup app seems to be <a href="http://www.bombich.com/software/ccc.html">Carbon Copy Cloner</a> for bootable backups (with installed psync also supports incremental backups); I also used <a href="http://www.owlfish.com/software/utils/RSyncBackup/">rsyncbackup</a> sometimes</li> <li><a href="http://www.maintain.se/cocktail/">Cocktail</a> is my choice as a frontend for admin tasks; <a href="http://krugazor.free.fr/software/desinstaller/DesInstaller.php">DesInstaller</a> lets you pick installed OS X installer packages to uninstall;</li> <li><a href="http://www.murderthoughts.com/software/">Damage Isolation</a> lets you mount iso-image-files; <a href="http://chmox.sourceforge.net/">CHMox</a> lets you open Windows help system files on your Mac</li> <li><a href="http://www.prosoftengineering.com/products/data_rescue_info.php">Data Rescue</a> was the most useful of its kind when I needed a tool for restoring data from a broken drive</li> <li><a href="http://hornware.com/sharepoints/">SharePoints</a> lets you share locations outside of home like other drives etc. via AppleShare (like you could before)</li> <li><a href="http://quicksilver.blacktree.com/">Quicksilver</a> is an interesting and useful app to access the content of your Mac; I never really got into it, but I suspect I should, so I list it here</li> <li><a href="http://kristopherjohnson.blogspot.com/2004/11/rouser-10-release.html">Rouser</a> is a small alarm clock, something I needed often when I didn't have it and never needed since I've got it...</li> <li><a href="http://www.lorax.com/FreeStuff/TextExtras.html">TextExtras</a> add stuff like Subscript to all Cocoa apps</li> <li><a href="http://www.unsanity.com/haxies/cleardock">ClearDock</a> clears or modifies the dock in other ways</li> <li><a href="http://www.unsanity.com/haxies/shapeshifter">ShapeShifter</a> allows for twaeing the entire UI, e.g. to make OS X look the way it should have with <a href="http://www.geocities.com/gershwix/">Gershwix</a></li> </ul> That should be it, I guess I'll keep this note updated to have an up-to-date resource for my personal choice of essential Mac apps. http://fsteeg.com/notes/mac-appshttp://fsteeg.com/notes/mac-apps Sat, 17 Feb 2007 00:00:01 +0000 authoringprogramming