FWEB
Protože jsem zjistil, že se na tuhle stránku sem tam někdo jukne, přidávám malý komentář, který (doufám) zlepší prvotní orientaci.
Fweb je nástroj, kterým lze sjednotit psaní kódu a dokumentaci k němu (obvykle C a TeX). Tahle stránka nemá býti učebnicí, na to viz odkazy. Obsahuje spíše zkratkovitý přehled příkazů, kterým FWeb rozumí. Pokud neradi čtete dokumentace,
můžete se zkusit podívat na příklad na konci textu, třeba z toho něco pochopíte :)
Základní idea je, že vŠechno napíšete do jednoho sOuboru s koncovkou .web, ze kterého pomocí programů fwave a ftangle vytlačíte jako výstup jednak .c a jednak .tex soubor. K tomu se v unixovém světě nádherně hodí makefile, kterým byste při čtení příkladu měli začít. Hodně štěstí.
Documentation - http://w3.pppl.gov/~krommes/fweb_toc.html
ftp - ftp://ftp.cstug.cz/pub/CTAN/web/fweb/
FAQ - http://www.desy.de/user/projects/LitProg/fweb-faq/top.html
The origins and philosophy of literate programming - D. E. Knuth, Literate Programming (Center for the Study of Language and Information, Leland Stanford Junior University, 1992).
WEB(plain) -> CWEB -> @FWEB{} (LaTeX, command line -P parameter...)
Mixture of languages in one FWEB run. ('Current language').
C(++), Fortran, RATFOR, TeX Itself :) ; language independent mode (verbatim)
C-like preprocessing
FWEB :
FTANGLE -> .c (is not intended for human eyes:)
FWEAVE -> .tex
Phases of Preprocessing:http://w3.pppl.gov/~krommes/fweb.html#SEC17
Integrating of FWEB: makefile
test.c: test.web
ftangle test
test.o: test.c
gcc -c test test.c
'@' - Command to fweb
@n - set global language to Fortran
@[L]ltext[options]
C c
C++ c++
Fortran-77 n
Fortran-90 n9
Ratfor-77 r
Ratfor-90 r9
TeX @tab x
VERBATIM v -> not yet fully debugged
Sections
Major(named) section - '@*' , period after name !
-> Table of Contents
@* = @*0 , n-level(0,1,2) ->translation to LaTeX section, subsection, subsubsection
Unnamed - @
Three times run of LaTex .tex -> .aux -> .tex (fwebmac.sty)
INDEX - last section, wich should be starred -> translate to TeX macro INDEX, overriding by index.name
Parts (FTANGLE=Code) -> Sections (non contiguous) -> Modules
source web structure - Structured into sections.
Each section : TeX part
Definition part
Code part
'Since sections can be combined into modules, there is no need for sections that must be physically contiguous in the output file to be contiguous in the source file. This allows for great flexibility in structuring the documentation of the code'
TeX Part
Can be straight text.
temporarily shift into code mode by enclosing the code within vertical bars ->Consider the C code fragment `|@c for(i=0; i<10; i++){}|', which ... -> output goes to .tex, not .c !
@c - if global language is not C
Definition Part
Consider the @m command --> Consider the @@m command
FWEB macros
Follow syntax of ANSI C, few extensions
variable arguments - @m VAR(x,y,z,...) text)
The tokens `#0' (number of variable arguments), `#n' (value of the nth optional argument), and `#.' (comma-delimited list of the optional arguments) are useful in this context.
!Recursion
ANSI C-compatible tokens
## --- Paste tokens on either side to form a new identifier.
#parameter --- Convert parameter to string (without expansion).
Extensions
#*param Like `#parameter', but pass a quoted string through unchanged.
#!param Don't expand argument.
#'param Convert parameter to a single-quoted string (no expansion).
#"param Convert parameter to a double-quoted string (no expansion).
#0 Number of variable arguments.
#n n-th variable argument, counting from 1.
#{0} Like `#0', but the argument may be a macro expression known at run time.
#{n} Like `#n', but the argument may be a macro expression.
#[0] The total number of arguments (fixed + variable). (The argument inside the brackets may be a macro expression.)
#[n] The nth argument (including the fixed ones), counting from 1. (The argument inside the brackets may be a macro expressions.
#. Comma-separated list of all variable arguments.
#:0 Unique statement number (expanded in phase 1).
#:nnn Unique statement number for each invocation of this macro (expanded in phase 2).
#< Begin a module name.
#, Internal comma; doesn't delimit macro argument.
@m FPRINTF(fmt,...) fprintf(fp,fmt,#.)
@f PLUS $_BINOP_
@m PLUS +
@m ADD(x, y) ((x) PLUS (y))
Without the format command, the `ADD' macro will pretty-print without spaces before and after the `PLUS'.
Outer macros
@d YES 1 - outer macro
FTANGLE -> quick way of #define
Code Part
@a
Named : '@<Module name@>'
Terminated by the next appearance of `@*' or @ASP{} (@) (which signal the beginning of a new section), or by the end of file.
There must be at least one @a ->otherwise FTANGLE gives void output.
Limbo section
before the first section. Only language @ allowed, other text only copied (FWEAVE) or ignored (FTANGLE) -> overrinding default FWEB macros. (Title...)
Standard definitions -> fwebmac.sty
LaTeX - after begin
Named Modules
@< Arbitrary TeX text |c code| @>
the same name in later section = accrete
Complete module name cannot be a subset of another
exempli gratia : Modul = Section1 +S3 +S10 ...
@a
for(i=1; i<n; i++)
@< Inner loop @>@;
@ Here's how to define a named module. Definitions may occur after use.
@< Inner...@>=
{
a[i] = i;
}
! Pseudo (invisible operators).
Input files
.fweb - Initialization (command lines, etc.)
.fweb.sty - style file (temporary files, default extensions, LaTeX..)( LaTeX.class.options = "twoside", LaTeX.package "indentfirst,multicol",...), .aux
name.web - Ehm.
name.ch - Change file - changing parts of file, without changing web source
name.hweb - code included by @iname.hch - Change file for include
FWEB commands
//debugging, commentnig styles
//Index entries -> @- delete, force, underline,...
//pretty printing, spaces @, , line break @/, no break @~, blank line @#, ...
@@ -> @
@| -> TeX: |
-> Code: breaks line
@ -> begin minor section (no contents, no name)
@* , @*n -> begin major section, can contain TeX commands (not fragile)
@; -> pseudo (invisible) semicolon. (lex. analyzation ->new lines in TeX)
@A -> code part begin
@a -> code part begin and mark (-> contents)
<@...@> -> module name
@c - C language
@c++
@d @D-> outer macros
@m @M -> macro definition -> especially for fortran programmers
@f mytype int -> makes @FWEAVE{} treat identifier like old_identifier (pretty printing - examlpe above)
module name -> scan .h file ...
@i -> include file
@O -> new output file name (FTANGLE)
@z .. @x -> ignorable material
@t -> put into hbox
@% -> comment (@%% - and skip lines)
/* */, // -> visible comment
Built-In functions
date time, dump macro definitions, absolute value, error messages, get value from environment variable, home directory,length of string, mathematical functions, minimum, upper/lower case,
Do LOOP:
$DO(I,0,2)
{
a[I] = I;
}
generates the three statements
a[0] = 0;
a[1] = 1;
a[2] = 2;
Customizing LaTeX output - http://w3.pppl.gov/~krommes/fweb_toc.html#TOC321 (index, numbering schemes, page headers, cross-references)
Converting an existing code to @FWEB{} - http://w3.pppl.gov/~krommes/fweb.html#SEC410