Blog Post

#1632 Build 1.0.60

brian Thu 1 Sep 2011

The latest build has been posted for download and online docs updated.

This build sports two huge new features: fanr and new doc infrastructure.

Fanr

All the code and tools for Fantom repositories are now available in this build. This includes:

  • new fanr pod for Repo APIs
  • new fanr command line for querying, installing from, and publishing to repos
  • file based repo implementation
  • web server and client implementations with REST protocol
  • a whole new docFanr manual which covers it all

What is not ready yet is an actual online repository to start sharing code. We plan to add this functionality to the fantom.org web site in the coming months. Although the technology is deployed in our commercial business and is getting some good field testing :-)

New Doc Infrastructure

Related to the fanr changes, is a completely redesigned documentation infrastructure which includes:

  • new file formats for docs distributed in pods
  • completely rewritten compilerDoc (replaces old docCompiler)
  • clean DOM for documentation loaded straight from pod zips (no more reflection)
  • reusable renderers for type, chapter, indexing HTML generation
  • reusable syntax modeling and HTML renderer for different programming languages

Since the new design lets us cleanly generate docs from pod without reflection, we now have more flexibility for building fanr documentation servers. When we add community fanr support to fantom.org, everybody's docs will be published with nice cross-linking and a centralized search engine.

With the new documentation engine, we decided to stop shipping HTML docs in the distribution since they consumed about a 1/3 of the total size. Instead you can now easily generate offline docs once you have new build installed using this command:

fan compilerDoc -all

The local docs are un-themed and will also let you easily re-doc any local pods you might also have.

As part of this new design, you will notice some differences in the docs:

  • top level index is more compressed
  • manual/chapter TOC navigation is much nicer for quick linking
  • pod-doc is now included in the pod index itself
  • source files are now by file instead of by type (avoiding dups)

Flux Syntax Changes

Part of the new doc rework, we pulled the syntax configuration files out of fluxText into a new reusable syntax pod. The configuration files themselves remain the same, but if you are a Flux user be aware of these changes:

  • syntax file now live in "etc/syntax/" instead of "etc/fluxText/syntax"
  • mapping of extensions to syntax files is done in "etc/syntax/ext.props"
  • syntax color coding is now configured in TextEditorOptions

The new API is easy to use if you want to generate syntax color coded HTML from any of the languages we support. See the new syntax docs.

API Enhancments

A couple of nice new API features to note:

Change Log

Build 1.0.60 (1 Sept 2011)

  • WebClient.proxy support
  • JsProps.writeProps: include etc/xxx files
  • WebOutStream: thead, tbody, tfoot
  • WebClient: postFile
  • Finish up fanr infrastructure
  • New docFanr chapter
  • Process.kill and bit of Java rework
  • Web support and docs for Expect: 100-continue
  • Env.promptPassword
  • fwt-js: onKeyDown/onKeyUp support for all widgets
  • fwt-js: keyboard support for Table, Dialog, Button
  • fwt-js: onBlur/onFocus support
  • Add fwt/table.fan example
  • Fix fwt::Table view/model bugs
  • wisp::Main to run simple WebMods under Wisp
  • Add deprecation warnings for facet fields
  • New compiler apidoc format
  • New syntax pod
  • New compilerDoc pod
  • Fandoc: shift heading levels-
  • Rework fluxText to depend on new syntax pod
  • Nuke old docCompiler
  • Remove doc target from build scripts
  • #1091: KeyDown not working in FWT/JS
  • #1558: js: DateTime.toHttpStr lacks JS implementation
  • #1576: Fix Java sys method reflection
  • #1617: Map.get returns default value for existing key if value is null

lbertrand Sat 3 Sep 2011

I tried to generate the documentation and have seen some errors. See below.

C:\DEV\FANTOM\fantom-1.0.60>fan compilerDoc -all
hello::/doc/Main.apidoc: Cannot parse sys::Err: Expected == <name>
  compilerDoc::ApiDocParser.parseType (ApiDocParser.fan:61)
  compilerDoc::ApiDocParser.parseType (ApiDocParser.fan)
  compilerDoc::DocPod.load (DocPod.fan:140)
  fan.sys.Func$Indirect1.call (Func.java:145)
  fan.sys.Map.each (Map.java:339)
  compilerDoc::DocPod.load (DocPod.fan:123)
  compilerDoc::DocPod.isManual (DocPod.fan:305)
  compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:201)
  fan.sys.List.each (List.java:528)
  compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:199)
  compilerDoc::FileDocWriter.write (FileDocWriter.fan:49)
  compilerDoc::Main.run (Main.fan:49)
  util::AbstractMain.main (AbstractMain.fan:370)
  java.lang.reflect.Method.invoke (Unknown)
  fan.sys.Method.invoke (Method.java:558)
  fan.sys.Method$MethodFunc.callOn (Method.java:230)
  fan.sys.Method.callOn (Method.java:139)
  fanx.tools.Fan.callMain (Fan.java:171)
  fanx.tools.Fan.executeType (Fan.java:136)
  fanx.tools.Fan.execute (Fan.java:41)
  1 More...
helloModularity::/doc/Main.apidoc: Cannot parse sys::Err: Expected == <name>
  compilerDoc::ApiDocParser.parseType (ApiDocParser.fan:61)
  compilerDoc::ApiDocParser.parseType (ApiDocParser.fan)
  compilerDoc::DocPod.load (DocPod.fan:140)
  fan.sys.Func$Indirect1.call (Func.java:145)
  fan.sys.Map.each (Map.java:339)
  compilerDoc::DocPod.load (DocPod.fan:123)
  compilerDoc::DocPod.isManual (DocPod.fan:305)
  compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:201)
  fan.sys.List.each (List.java:528)
  compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:199)
  compilerDoc::FileDocWriter.write (FileDocWriter.fan:49)
  compilerDoc::Main.run (Main.fan:49)
  util::AbstractMain.main (AbstractMain.fan:370)
  java.lang.reflect.Method.invoke (Unknown)
  fan.sys.Method.invoke (Method.java:558)
  fan.sys.Method$MethodFunc.callOn (Method.java:230)
  fan.sys.Method.callOn (Method.java:139)
  fanx.tools.Fan.callMain (Fan.java:171)
  fanx.tools.Fan.executeType (Fan.java:136)
  fanx.tools.Fan.execute (Fan.java:41)
  1 More...
modularity::/doc/Modularity.apidoc: Cannot parse sys::Err: Expected == <name>
  compilerDoc::ApiDocParser.parseType (ApiDocParser.fan:61)
  compilerDoc::ApiDocParser.parseType (ApiDocParser.fan)
  compilerDoc::DocPod.load (DocPod.fan:140)
  fan.sys.Func$Indirect1.call (Func.java:145)
  fan.sys.Map.each (Map.java:339)
  compilerDoc::DocPod.load (DocPod.fan:123)
  compilerDoc::DocPod.isManual (DocPod.fan:305)
  compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:201)
  fan.sys.List.each (List.java:528)
  compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:199)
  compilerDoc::FileDocWriter.write (FileDocWriter.fan:49)
  compilerDoc::Main.run (Main.fan:49)
  util::AbstractMain.main (AbstractMain.fan:370)
  java.lang.reflect.Method.invoke (Unknown)
  fan.sys.Method.invoke (Method.java:558)
  fan.sys.Method$MethodFunc.callOn (Method.java:230)
  fan.sys.Method.callOn (Method.java:139)
  fanx.tools.Fan.callMain (Fan.java:171)
  fanx.tools.Fan.executeType (Fan.java:136)
  fanx.tools.Fan.execute (Fan.java:41)
  1 More...
Writing pod 'build' ...
Writing pod 'compiler' ...
Writing pod 'compilerDoc' ...
Writing pod 'compilerJava' ...
Writing pod 'compilerJs' ...
Writing pod 'concurrent' ...
Writing pod 'docFanr' ...
Writing pod 'docIntro' ...
Writing pod 'docLang' ...
Writing pod 'docTools' ...
Writing pod 'dom' ...
Writing pod 'email' ...
Writing pod 'fandoc' ...
Writing pod 'fanr' ...
Writing pod 'fansh' ...
Writing pod 'flux' ...
Writing pod 'fluxText' ...
Writing pod 'fwt' ...
Writing pod 'gfx' ...
Writing pod 'hello' ...
Writing pod 'helloModularity' ...
Writing pod 'inet' ...
Writing pod 'modularity' ...
Writing pod 'obix' ...
Writing pod 'sql' ...
Writing pod 'syntax' ...
Writing pod 'sys' ...
Writing pod 'util' ...
Writing pod 'web' ...
Writing pod 'webmod' ...
Writing pod 'wisp' ...
Writing pod 'xml' ..  .

Also, the doc directory is created under the user's work environment - Should it not be inside the fan main environment where the distribution is installed?

brian Sat 3 Sep 2011

You will need to recompile all your modules.

Yeah, should be no problem to switch default to working env. Good idea. In meantime you can just specify -outDir on command line to say where you want it.

lbertrand Sat 3 Sep 2011

What do you mean by recompoiling all the modules?

I just took the distribution from the website, unzipped it and ran the fan compilerDoc -all command.

I tried again but I had the same errors - is it a problem with the 1.0.60 distribution?

andy Sat 3 Sep 2011

Your installation is picking up some non-dist pods (hello, helloModularity, modularity) - since the docapi format changed with how docs are stored inside pods - those pods will need to get rebuilt for fan compilerDoc to work on them. Or just nuke them out of your lib/fan dir if not needed.

lbertrand Sat 3 Sep 2011

Ok, understood - these pods are some test pods I made a while back... Just need to build them again.

But this leads me to wonder about how this works. I was thinking that it will only build the documentation of the core Fantom distro, and not mix the documentation with my own pods... I think that by default documentation of each pod should be built where it is - so there are no mix up between core distro and own users pod...

jessevdam Sun 4 Sep 2011

The sources of the compiler pod are nicely grouped in different folders, it would nice that the doc also would hold this same grouping of the classes.

peter Mon 5 Sep 2011

Thanks for all the work on the new build. It would help to have a readme in the download folder, especially now docs are not included, to help newcomers get started.

The new documentation system is more convenient for offline browsing, as the non doc headings are not present. But links to examples are not working for me, a protocol error, they worked in the earlier version.

Login or Signup to reply.