Fandoc Viewer v1.0.10 Released!

Fandoc Viewer is a flux extension to display and edit fandoc files.

• Fantom-Factory: http://www.fantomfactory.org/pods/afFandocViewer
• Install: fanr install -r http://repo.status302.com/fanr/ afFandocViewer
• API & Docs: http://repo.status302.com/doc/afFandocViewer/#overview
• Source: https://bitbucket.org/AlienFactory/affandocviewer

Fandoc Viewer lets you...

• View Fantom Docs Offline
• Surf the Web
• View and Edit Fandoc Files
• Syntax Highlighting & More!

View Fantom Docs Offline!

Fandoc Viewer lets you view all the documentation in your current Fantom installation by adding a fandoc uri scheme to flux.

Try these command lines:

C:\> flux fandoc://docLang
C:\> flux fandoc://afFandocViewer
C:\> flux fandoc://sys/Uri

Wow! It looks just like the Fantom website!

And all your favourite Alien-Factory pods are there too! The scheme follows the format:

fandoc://${podName}/${typeName}

Surf The Web!

Fandoc Viewer works by adding a web browser view to flux. That means you can also do this:

C:\> flux http://www.alienfactory.co.uk/

View and Edit Fandoc Files!

Render plain text files as Fandocs and edit them!

By giving files a .fandoc extension, flux will automatically open them as Fandocs! This is great for editing pod.fandoc files, previewing long Sidewalk articles, or just keeping notes in a fandoc format.

It works in code too! Use the fan:// scheme to view a Fandoc pod resource. This makes it easy for flux applications to view help pages and other documentation! Consider:

try {
    ...
} catch (Err r) {
    flux::Frame.load(`fan://myPod/doc/help.fandoc`)
}

Note this feature requires Flux Tools to be installed.

Flux Tools

Install Fandoc Viewer Flux Tools to add lots of little extras to flux.

C:\> fan afFandocViewer -install

The installation alters several Fantom property files. But rest assured, backups are made to any file touched. The installation also respects your work dir, should you be using PathEnv and have the FAN_ENV_PATH environment variable set.

The installation adds the following:

Fandoc Cmd

A simple fandoc.cmd file is copied to %FAN_HOME%\bin\ which launches Fandoc Viewer. It makes it possible to do this:

C:\> fandoc docLang
C:\> fandoc fan://flux/doc/pod.fandoc
C:\> fandoc http://www.alienfactory.co.uk/

Note Linux users will have to give the fandoc file executable permission.

Syntax Highlighting

A flux text syntax file is installed and enabled to give your fandoc editing a flair of colour!

Fandoc CSS files

Fandoc CSS files are installed locally so you may style your fandoc and pod documentation as you like!

Fandoc Index Tool

This handy flux tool lets you view all installed Fantom documentation as soon as you hit F1!

View / Edit Fandoc Tool

This nifty flux tool lets you preview your fandoc editing with a single key press!

Hit F12 to edit any file based fandoc file, then hit F12 again to save and preview your edits!

Extension to MimeType Patch

Flux will render any file ending with .fandoc as a fandoc - it just takes this simple patch!

TIP: Associate the .fandoc extension with fandoc.cmd in your OS. Now you can double click on any .fandoc file to view and edit it!

F5 Browser Refresh

Now you have a browser view in flux, you're probably in the habit of using F5 to refresh!

Use this patch to un-bind Find Next from F5 and bind a refresh command instead. Don't worry, Ctrl+F still brings up the Find dialogue box!

Oh, hell yeah. Nice!

I had done something kinda like that a while back (flux fandoc side panel): https://bitbucket.org/tcolar/fluxy/src/43d770c1cf0f3023f877b27046ebd9b7f20f4966/fluxy/fan/sidebars/FandocSidebar.fan?at=default

but yours looks better :)

@tcolar, Thanks!

I tried fluxy side bar the other day but due to the Windows SWT / IE WebBrowser serving up relative urls with a dodgy about schema, it didn't work. :(

I do like your idea of a search bar / command though...

ha ok you're probably right, I haven't used flux in a while. The one in camembert should work thugh.

Just to say I've recently updated Fandoc Viewer (v1.0.8) to include an install script. (I was setting up a new dev machine for myself.)

To use:

C:\> fanr install -r http://repo.status302.com/fanr/ afFandocViewer
     ...
C:\> fan afFandocViewer -install
     ...

For those who don't know, Fandoc Viewer lets you view all the documentation in your current Fantom installation, offline!

After installing, try these:

C:\> fandoc docLang
C:\> fandoc sys

Wow! It looks just like the Fantom website!

And all your favourite Alien-Factory pods are there too!

Personally, I find it an invaluable tool for writing Fantom documentation.

The install configures flux key bindings, adds syntax highlighting (for fandoc editing), and copies some tool scripts over. All config files are backed up with a .orig extension and the output is pretty verbose, so it should be fine to say Yes to auto-install.

Key bindings are re-mapped to the following:

• F1 --> Brings up the documentation home page
• F5 --> Refreshes the browser
• F12 --> Flips between edit and preview modes.

The default in flux, is to have F5 mapped to Find Next. The install re-maps this to Ctrl+F5. Ctrl+F still brings up the Find Dialogue though.

Now if only I could get flux text to word wrap...

I do the fanr install, then the fan afFandocViewer -install, then chmod +x fandoc.

fan fandoc:// leads to ERROR: sys::UnknownPodErr: fandoc://

fandoc fandoc:// leads to :not foundel/software/fantom/bin/fandoc: 1: /home/michael/software/fantom/bin/fandoc: followed next line by /home/michael/software/fantom/bin/fandoc: 2: /home/michael/software/fantom/bin/fandoc: @fan: not found

Any ideas?

Yeah, my posting is wrong! Try these:

C:\> fan afFandocViewer afFandocViewer
C:\> fan afFandocViewer sys

C:\> fandoc afFandocViewer
C:\> fandoc sys

The fandoc script is just fan afFandocViewer *, helps to type less on the command line. It can be followed by a pod name (e.g. sys, afFandocViewer), file or url.

Maybe I should add a shortcut for the index page, like C:\>fandoc / ?

@fan: not found

Not sure why the fandoc script isn't working, it's a straight copy of the flux, fant and fanr scripts bundled with Fantom:

#!/bin/bash

. "${0%/*}/fanlaunch"
fanlaunch Fan afFandocViewer "$@"

Does flux work?

$ flux fandoc://docLang

flux fandoc://docLang works fine. So does fan afFandocViewer fandoc://. fan fandoc:// fails, though, with that "not found" error.

So...

I look into fandoc:

@fan afFandocViewer %*

Oops. You've got the CMD file in the shell script.

Then I look into fandoc.cmd. That's where the shell script is. :D

Oh, yeah! The offending code in the install script:

copyToHomeDir(`/res/bin/fandoc.cmd`, `bin/fandoc`)
copyToHomeDir(`/res/bin/fandoc`,     `bin/fandoc.cmd`)

That's brilliant! :D

Thanks for spotting and reporting! I'll re-release soon... I may just make the cmd line parameter a bit more intelligent first...

It did make me wonder if there could be a more generic approach to installing cmds & scripts, similar to what Ruby and Node do...?

Just to say I've uploaded Fandoc Viewer v1.0.10. The scripts have been swapped round to their correct names and the cmd line parameter processing is a little more intelligent. It looks for Type names and corrects lower casing and qnames. The following are all valid:

C:\> fandoc /
C:\> fandoc sys/Uri
C:\> fandoc sys::uri
C:\> fandoc afioc

• Fantom-Factory: http://www.fantomfactory.org/pods/afFandocViewer
• Install: fanr install -r http://repo.status302.com/fanr/ afFandocViewer
• API & Docs: http://repo.status302.com/doc/afFandocViewer/#overview
• Source: https://bitbucket.org/AlienFactory/affandocviewer