data/shellFunctions/doxyToAsciidoc.awk

   1 #-------------------------------------------------------------------------------
   2 #               ______                _     ____          __  __
   3 #              |  ____|             _| |_  / __ \   /\   |  \/  |
   4 #              | |__ _ __ ___  ___ /     \| |  | | /  \  | \  / |
   5 #              |  __| '__/ _ \/ _ ( (| |) ) |  | |/ /\ \ | |\/| |
   6 #              | |  | | |  __/  __/\_   _/| |__| / ____ \| |  | |
   7 #              |_|  |_|  \___|\___|  |_|   \____/_/    \_\_|  |_|
   8 #
   9 #                   FreeFOAM: The Cross-Platform CFD Toolkit
  10 #
  11 # Copyright (C) 2008-2009 Michael Wild <themiwi@users.sf.net>
  12 #                         Gerber van der Graaf <gerber_graaf@users.sf.net>
  13 #-------------------------------------------------------------------------------
  14 # License
  15 #   This file is part of FreeFOAM.
  16 #
  17 #   FreeFOAM is free software; you can redistribute it and/or modify it
  18 #   under the terms of the GNU General Public License as published by the
  19 #   Free Software Foundation; either version 2 of the License, or (at your
  20 #   option) any later version.
  21 #
  22 #   FreeFOAM is distributed in the hope that it will be useful, but WITHOUT
  23 #   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  24 #   FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  25 #   for more details.
  26 #
  27 #   You should have received a copy of the GNU General Public License
  28 #   along with FreeFOAM; if not, write to the Free Software Foundation,
  29 #   Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  30 #
  31 # Script
  32 #     doxyToAsciidoc.awk
  33 #
  34 # Description
  35 #     Transform human-readable tags such as 'Description' into the Asciidoc
  36 #     equivalent. It takes the variables 'name', 'exe_prefix',
  37 #     'exe_prefix_upper' and 'version' as arguments (the last one is required).
  38 #
  39 #------------------------------------------------------------------------------
  40
  41 # add a new section
  42 function new_section(name) {
  43    n_sections++;
  44    current_section=n_sections;
  45    text[current_section] = "";
  46    section_titles[current_section] = name;
  47    section_indices[name] = current_section;
  48 }
  49
  50 # delete a section
  51 function delete_section(name) {
  52    idx=section_indices[name];
  53    delete section_titles[idx];
  54    delete section_indices[name];
  55    delete text[idx];
  56 }
  57
  58 # add text to the buffer
  59 function add_text(str) {
  60    text[current_section] = text[current_section] str;
  61 }
  62
  63 # set default text in a section and create the secion if it doesn't exist
  64 function set_default_text(str,sect_name) {
  65    bak = current_section;
  66    if( ! (sect_name in section_indices) ) {
  67       new_section( sect_name );
  68    }
  69    current_section = section_indices[sect_name];
  70    if( !length(text[current_section]) ) {
  71       add_text( str );
  72    }
  73    current_section = bak;
  74 }
  75
  76 # if necessary, push a list level (worker function)
  77 function push_list(type,indent){
  78    if( indent>list_indents[list_level] ||
  79        ( indent==list_indents[list_level] &&
  80          type!=list_stack[list_level] ) ){
  81       list_level++;
  82       list_stack[list_level]=type;
  83       list_indents[list_level]=indent;
  84       in_list=1;
  85       if( list_level > 1 )
  86          add_text("+\n--\n");
  87       return 1;
  88    }
  89 }
  90
  91 # pop a list level without asking (worker function)
  92 function pop_list_work(){
  93    delete list_stack[list_level];
  94    delete list_indents[list_level];
  95    list_level--;
  96    if( list_level > 0 ) {
  97       add_text( "--\n" );
  98    }
  99 }
 100
 101 # if necessary, pop list levels
 102 function pop_list(type,indent){
 103    popped_list = 0;
 104    if( type == "term" ){
 105       while( list_indents[list_level] >= indent ) {
 106          pop_list_work();
 107          popped_list = 1;
 108       }
 109       return;
 110    }
 111    while( list_indents[list_level] > indent ||
 112           list_stack[list_level] != type ){
 113       pop_list_work();
 114       popped_list = 1;
 115    }
 116    if( !list_level )
 117       in_list=0;
 118    if( in_list && popped_list )
 119       add_text( "+\n" );
 120 }
 121
 122 # flush all lists
 123 function flush_lists(){
 124    if( in_list ) {
 125       pop_list("term",list_indents[1]);
 126    }
 127    in_list = 0;
 128 }
 129
 130 # the general list element handler to be called by code
 131 function handle_list(type){
 132    ispace=gensub(/^( *)[^ ].*$/,"\\1",1,$0);
 133    indent=length(ispace);
 134    if( type == "term" ) {
 135      pop_list(type,indent);
 136      return;
 137    }
 138    if( push_list(type,indent) ) return;
 139    pop_list(type,indent);
 140 }
 141
 142 BEGIN{
 143    in_head=0;
 144    in_description=0;
 145    in_brief=0;
 146    in_doc=0;
 147    brief="";
 148    commentbar="/////////////////////////////////////////////////////////";
 149    current_section=-1;
 150    n_sections=0;
 151    list_level=0;
 152    list_indents[0]=-1;
 153    list_stack[0]="top";
 154    in_list=0;
 155    options="";
 156    strip_regex="^[[:space:]]*";
 157 };
 158
 159 NR==1{
 160    if( !length(name) ) {
 161       name=gensub(/\..*$/,"","g",gensub(/^.*\//,"","g",FILENAME));
 162    }
 163    if( !length(version) ) {
 164       print "Variable 'version' not provided on the command line." > "/dev/stderr";
 165       exit 1;
 166    }
 167    name_upper = exe_prefix_upper toupper(name);
 168    name = exe_prefix name;
 169    print commentbar;
 170    print "THIS FILE WAS AUTOMATICALLY GENERATED FROM:";
 171    print "  " FILENAME;
 172    print "CHANGES TO THIS FILE WILL BE LOST! EDIT THE";
 173    print "ABOVE MENTIONED SOURCE FILE INSTEAD.";
 174    print commentbar;
 175    print "= " name_upper "(1) =";
 176    print ":mansource: FreeFOAM";
 177    print ":manversion: " version;
 178    print ":manmanual: FreeFOAM Manual";
 179    print "";
 180    print "NAME";
 181    print "----";
 182 }
 183
 184 # the header comments start
 185 /^\/\*-----+\*\\$/{
 186    in_head=1;
 187    next;
 188 }
 189
 190 # the header comments stop
 191 /\*\//{
 192    in_head=0;
 193    in_doc=0;
 194    flush_lists();
 195    exit 0;
 196 }
 197
 198 # the first paragraph will be 'brief' and the others 'detail'
 199 in_head && /^Description/{
 200    in_description=1;
 201    in_brief=1;
 202    in_doc=1;
 203    new_section("Brief");
 204    next;
 205 }
 206
 207 # special sections
 208 in_doc && /^(Notes?|Usage|Author|See *Also)$/{
 209    flush_lists();
 210    sub(/See *Also/,"SeeAlso",$0);
 211    sub(/Notes?/,"Note",$0);
 212    new_section($0);
 213    next;
 214 }
 215
 216 # strip leading indent from documentation text
 217 in_head && /^    /{
 218    sub(/^    /,"",$0);
 219 }
 220
 221 # watch out for the end of the brief paragraph
 222 in_brief {
 223    if( !length($0) ) {
 224       in_brief=0;
 225       new_section("Description");
 226       next;
 227    }
 228    add_text( " " $0 );
 229    next;
 230 }
 231
 232 # swallow the "- name [OPTIONS]" line with the following paragraph in the "Usage" section
 233 # TODO find a better solutio for the swallowd paragraph. But mostly it is the same as the brief
 234 # description anyways...
 235 in_doc && section_titles[current_section] == "Usage" && /^[[:space:]]*- .*\[OPTIONS?\]/,/^$/ {
 236    next;
 237 }
 238
 239 # formatting commands
 240 #####################
 241
 242 # @em or @a
 243 /[\\@](em?|a)[[:space:]]+[^[:space:]]+/ {
 244    $0 = gensub(/[\\@](em?|a)[[:space:]]+([^[:space:]]+)/,"__\\2__","g",$0);
 245 }
 246
 247 # <em>
 248 /<\/?em>/ {
 249    gsub(/<\/?em>/,"__",$0);
 250 }
 251
 252 # @b
 253 /[\\@]b[[:space:]]+[^[:space:]]+/ {
 254    $0 = gensub(/[\\@]b[[:space:]]+([^[:space:]]+)/,"**\\1**","g",$0);
 255 }
 256
 257 # <b>
 258 /<\/?b>/ {
 259    gsub(/<\/?b>/,"**",$0);
 260 }
 261
 262 # @c or @t
 263 /[\\@][cp][[:space:]]+[^[:space:]]+/ {
 264    $0 = gensub(/[\\@][cp][[:space:]]+([^[:space:]]+)/,"++\\1++","g",$0);
 265 }
 266
 267 # <tt>
 268 /<\/?tt>/ {
 269    gsub(/<\/?tt>/,"++",$0);
 270 }
 271
 272 # @todo
 273 /[\\@]todo/ {
 274    $0 = gensub(/[\\@]todo/,"**TODO**","g",$0);
 275 }
 276
 277 # @verbatim
 278 /[\\@]verbatim/ {
 279    str = ".............\n";
 280    if( in_list ) {
 281       str = "+\n--\n" str;
 282    }
 283    add_text(str);
 284    nindent = length( gensub(/^([[:space:]]*).*$/,"\\1",1,$0) );
 285    strip_regex = "^[[:space:]]{1," nindnet "}";
 286    next;
 287 }
 288
 289 # @endverbatim
 290 /[\\@]endverbatim/ {
 291    str = ".............\n";
 292    if( in_list ) {
 293       str = str "--\n+\n";
 294    }
 295    add_text(str);
 296    strip_regex = "^[[:space:]]*";
 297    next;
 298 }
 299
 300 # \< and \>
 301 /\\[<>]/ {
 302    $0 = gensub(/\\([<>])/,"\\1","g",$0);
 303 }
 304
 305 # lists
 306 #######
 307
 308 # parameter list
 309 /^[[:space:]]*[\\@]param[[:space:]]+/ {
 310    handle_list("param");
 311    sub(/[[:space:]]*(\\n)?$/,"",$0);
 312    # special treatment for Usage section (ugly)
 313    if( section_titles[current_section] == "Usage" ) {
 314       # check whether it is a -opt option
 315       if( $0 ~ /^[[:space:]]*[\\@]param[[:space:]]*-[^[:space:]]+/ ) {
 316          opt = gensub(/^[[:space:]]*[\\@]param[[:space:]]*([^:]*[^[:space:]])([[:space:]]+:.*)?$/,"\\1",1,$0);
 317          options = options " [" gensub(/^([^[:space:]]+)[[:space:]]+(.*)/,"\\1 '\\2'",1,opt) "]";
 318          $0 = gensub(/^[[:space:]]*[\\@]param[[:space:]]+([^[:space:]]+)[[:space:]]*([[:space:]][^:]+[^[:space:]])?[[:space:]]*(:[[:space:]]*(.*))?$/,
 319             "*\\1*\\2 ::\\4","g",$0);
 320          $0 = gensub(/^[[:space:]]*(\*[^[:space:]]+\*)[[:space:]]*([^[:space:]].*[^[:space:]])[[:space:]]*::/,"\\1 '\\2' ::",1,$0);
 321       } else {
 322          # no, it is an argument
 323          opt = gensub(/^[[:space:]]*[\\@]param[[:space:]]*([^:]*[^[:space:]])([[:space:]]+:.*)?$/,"\\1",1,$0);
 324          options = options " '" opt "'";
 325          $0 = gensub(/^[[:space:]]*[\\@]param[[:space:]]+(<[^>]+>)$/, "'\\1' ::","g",$0);
 326       }
 327    } else {
 328       $0 = gensub(/^([[:space:]]*)[\\@]param[[:space:]]+([^:]+[^ \t])( *: *(.*))?$/,"\\1'\\2'::\n\\4","g",$0);
 329    }
 330 }
 331
 332 # ordered list
 333 /^[[:space:]]*-# / {
 334    handle_list("ordered");
 335    sub(/-#/,". ",$0);
 336 }
 337
 338 # unordered list
 339 /^[[:space:]]*- / {
 340    handle_list("unordered");
 341 }
 342
 343 # list termination
 344 /^[[:space:]]*  \.$/ {
 345    handle_list("term");
 346    sub(/  \.$/,"+",$0);
 347 }
 348
 349 # output
 350 ########
 351
 352 # all doc lines are printed with all leading space stripped
 353 in_doc {
 354    sub(strip_regex,"",$0);
 355    add_text($0 "\n");
 356 }
 357
 358 # do nothing by default
 359 {}
 360
 361 # write text and boilerplate footer
 362 END {
 363    set_default_text(" **TODO** brief description\n","Brief");
 364    set_default_text("**TODO** extended description\n","Description");
 365    print name " -" text[section_indices["Brief"]] "\n";
 366    print "SYNOPSIS";
 367    print "--------";
 368    print "*" gensub(/^(freefoam)-/,"\\1 ",1,name) "*" options " [-help] [-doc] [-srcDoc]\n";
 369    print "DESCRIPTION";
 370    print "-----------";
 371    print text[section_indices["Description"]];
 372    print "OPTIONS";
 373    print "-------";
 374    set_default_text("**TODO** add 'Usage' section\n","Usage");
 375    print text[section_indices["Usage"]];
 376    delete_section("Brief");
 377    delete_section("Description");
 378    delete_section("Usage");
 379    for( sect in section_indices ) {
 380       if( sect != "SeeAlso" ) {
 381          idx = section_indices[sect];
 382          print toupper(sect);
 383          print gensub(/./,"-","g",sect);
 384          print text[idx];
 385       }
 386    }
 387    print "SEE ALSO";
 388    print "--------";
 389    if( length(text[section_indices["SeeAlso"]]) ) {
 390       print text[section_indices["SeeAlso"]];
 391    }
 392    print "\
 393 An overview of FreeFOAM is given in linkff:freefoam[7]. For information\n\
 394 on the configuration of FreeFOAM, refer to linkff:freefoam-config[7].\n\
 395 \n\
 396 AUTHOR\n\
 397 ------\n";
 398    set_default_text("OpenCFD Ltd.\n","Author");
 399    print text[section_indices["Author"]];
 400    print "\nFREEFOAM\n\
 401 --------\n\
 402 Part of the linkff:freefoam[7] suite.\n\
 403 \n\
 404 COPYRIGHT\n\
 405 ---------\n\
 406 Copyright (C) 2009 Michael Wild.\n\
 407 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\
 408 Permission is granted to copy, distribute and/or modify this document under the\n\
 409 terms of the GNU Free Documentation License, Version 1.3 or any later version\n\
 410 published by the Free Software Foundation; with no Invariant Sections, no\n\
 411 Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available\n\
 412 from http://www.gnu.org/copyleft/fdl.html\n\
 413 \n\
 414 Copyright (C) 1991-2009 OpenCFD Ltd.\n\
 415 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\
 416 OpenFOAM is free software; you can redistribute it and/or modify\n\
 417 it under the terms of the GNU General Public License as published by the Free\n\
 418 Software Foundation; either version 2 of the License, or (at your option) any\n\
 419 later version. A copy of the license is available from\n\
 420 http://www.gnu.org/licenses/old-licenses/gpl-2.0.html\n\
 421 \n\
 422 Copyright (C) 2008-2009 Michael Wild.\n\
 423 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\
 424 FreeFOAM is free software; you can redistribute it and/or modify it under the\n\
 425 terms of the GNU General Public License as published by the Free Software\n\
 426 Foundation; either version 2 of the License, or (at your option) any later\n\
 427 version. A copy of the license is available from\n\
 428 http://www.gnu.org/licenses/old-licenses/gpl-2.0.html"
 429    print "\n" commentbar "\nvim: set ft=asciidoc:\n" commentbar;
 430    #
 431 }
 432
 433 # ------------------------- vim: set sw=3 sts=3 et: --------------- end-of-file