First, relatively good news: flx_web is sitting on 3% memory. [I have a cron job that regularly deletes the log file so we don't get disk full]
Next .. since everyone complained .. the webserver now has a new format for fdoc files. This will be up shortly as a demo for your criticism ... http://felix-lang.org/share/src/web/ref/spec_01.fdoc http://felix-lang.org/share/src/lib/std/strings/string.fdoc http://felix-lang.org/share/src/lib/std/datatype/list.fdoc Basically there's a left margin menu similar to ReadTheDocs (RTD) [I'm pretty good at stealing other people's ideas, integrating them, and making them .. er .. well .. 'better' .. :] Please excuse the colour scheme (I like high contrast bright colours when testing so I can see the HTML boxes easily .. makes things easier to line up). Also don't forget Felix serves docs with a long expiry period so you can browse from you local cache, so if you've been browsing recently you may have to force a reload. ==================================================== Advantages of RTD: * produces PDF * HTML works on any webserver * currently looks a bit sexier * maintained by someone else :) * active project with many users * docs live on a separate webserver * fast automatic rebuild of docs (based on commits to Github) Advantages of fdoc * no third party software required * layout actually works (RTD is broken) * works with all existing fdoc files * is under our control * HTML generated on the fly * fdoc is a better format the RST * integrates with Felix code better hyperlinks, colouring, tooltips: in fact remember Felix can *execute* fdocs, and some library code (eg string) is in fdoc format already * can be modified to do what we want BUGS: browser BACK goes to previous URL including #tag, not previous document. Disadvantage of both systems * when clicking on a level 1 heading, the tree redisplay causes the mouse to now be over some unrelated section. This is bad UI design really. ========================================================= Improvement, issue, ideas etc. Contribute! Both RTD and my new code have a big disadvantage: they can't work properly on a phone. The left margin menu is fixed width. RTD makes the menu go away if the window is too small. Making a user controlled menu width is simple enough in principle, however it means all the style stuff has to be calculated in Javascript. Then the boundary can be made draggable, we can set a variable, and have the widths controlled by that variable. Many fdocs only have one level 1 heading. This really defeats the utility of the menu. Partly this is because there was no @title feature in the old days so the h1 heading served as the title. The fdocs could be edited but another idea is to make the menu code a bit smarter, e.g. if there is only one h1 heading, provide the tree based on h2 headings instead. The menu could also be expanded to 3 levels. Another option is to not do the collapsing stuff if the whole menu fits (i.e. view it as a space optimisation). The behaviour would then be a bit inconsistent. ======================================================= It would be useful to produce a translator for RST for the webserver though. It makes sense for tool --help output to be RST. Restructured text was designed to be readable as plain text, as well as being typeset. It is a lot better at that than, say, fdoc. With an RST translator, the tool documentation "quick guide" can be produced by simply running the tools with --help option. Any volunteers? Its an interesting project to do in Felix. I can provide the infrastructure for the webserver but a standalone program to do the translation would be interesting. Although of course you could just use sphinx. :) ====================================================== A more useful project might be an fdoc to RST translator. That's a much simpler program than RST to HTML translator. A pretty good tutorial task for a beginner Felix programmer. -- john skaller skal...@users.sourceforge.net http://felix-lang.org ------------------------------------------------------------------------------ Want excitement? Manually upgrade your production database. When you want reliability, choose Perforce. Perforce version control. Predictably reliable. http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk _______________________________________________ Felix-language mailing list Felix-language@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/felix-language
