On 02/01/2014, at 9:44 AM, srean wrote: > Hey John > > could you explain how to use fdoc features and the literate programming > features.Or better still, have a page on it in the tutorials. I recall a > thread on the mailing list about this but cant seem to find it. >
Sure, well in general an *.fdoc file is HTML with some extra special bits written as commands like @command arguments ..maybe some text here @next_command ... The full list of commands is in "handle_command" in this file: http://felix-lang.org/$/usr/local/lib/felix/felix-latest/share/src/lib/plugins/fdoc2html.flx The most common commands are @h1 heading @h2 heading etc, for HTML headings. Special commands are used so a collapsable tree can be created. Another common one is: @felix var some = felix; @ and similarly @c++ @pre @ocaml @python You can also do an "external" variant: @felix filename.flx which displays the file. Good for pointing at library code if you can figure out how to get the filename right. Note that since Felix supports a lot of \LaTex + \AMSTeX operator symbols these are displayed using MathJax. Inside text the only {markup} is curly braces to denote courier font, i.e. names from code. There are some commands for slideshows: @slideshow @slide @section @slideshow starts the slides @slide marks the start of a whole slide @section breaks the slide into pieces which are displayed with a delay SPECIAL FORMATS ================ There is a special format of fdoc which has MANDATORY BLANK LINE AT TOP @felix ... @ More gibberish .... @expect .... @ .... Any number of @felix and @expect sections are allowed. This has two magics. The first is flx_tangle which packs the @felix sections into a felix file filename.flx and the @expect sections into a filename.expect. After running flx_tangle you can the run flx --expect filename.flx and it will automatically run the felix program AND check the output is what you expected. Together with another extension of "flx" which allows processing all files matching a regex, this is how the test suite is run in a single "flx" command. See "make test". There is a second piece of magic. Felix can EXECUTE *.fdoc files directly. In fact this is done with a hack: \n --> @felix\n and @.*\n --> @felix\n are a special form of comment just like /* .. */ so the parser just skips over the documentation and runs the embedded felix code. Unfortunately it cannot tangle out the expect files as well at the moment (you need flx_tangle to do that). All tutorials should use the @felix @expect format if possible because it means it is possible to actually CHECK that the examples really work and not lie to readers. It also means we get free regression tests. However the format isn't really very flexible, eg it isn't enough to test separate compilation (because only one felix file is allowed). The other thing is files named *_99.fdoc where 99 is any integer. If you do that the webserver automatically gives you PREV and NEXT buttons. So you had better make sure you number documents sequentially. There is a tool flx_mktutindex to make the index page (basename_index.fdoc). See "make gen-doc" to see how it is used. There's another tool src/tools/flx_renumber.flx (which isn't being built at the moment but of course you can just run it with "flx"). This is used like flx src/tools/flx_renumber target-dir regex src99 target99 where target-dir us usually src/web regex is usually 'tutorial_(\d).fdoc and src99 and target99 are the first number to move and the new number of that file. This can be used to delete files from a tutorial sequence or to make space for a new file. It automatically copies files from the right end. Hope that's enough to experiment and come back with "Why does this fail?" and "How do I do this?" questions. -- john skaller skal...@users.sourceforge.net http://felix-lang.org ------------------------------------------------------------------------------ Rapidly troubleshoot problems before they affect your business. Most IT organizations don't have a clear picture of how application performance affects their revenue. With AppDynamics, you get 100% visibility into your Java,.NET, & PHP application. Start your 15-day FREE TRIAL of AppDynamics Pro! http://pubads.g.doubleclick.net/gampad/clk?id=84349831&iu=/4140/ostg.clktrk _______________________________________________ Felix-language mailing list Felix-language@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/felix-language
