From e8181411e64048ce47cd6529301d8658c1db2480 Mon Sep 17 00:00:00 2001 From: ibs Date: Thu, 27 Feb 2014 18:33:30 +0400 Subject: [PATCH] 0024364: Document system should use local MathJax also the new ability choosing of the location of MathJax was introduced new argument was added to gendoc.bat script MathJax choice was updated for CHM articles Minor corrections of documentation --- dox/dev_guides/documentation/documentation.md | 76 +++--------- dox/occdoc.tcl | 111 ++++++++++++++---- 2 files changed, 104 insertions(+), 83 deletions(-) diff --git a/dox/dev_guides/documentation/documentation.md b/dox/dev_guides/documentation/documentation.md index 9ad43e71ed..0e9c46074c 100644 --- a/dox/dev_guides/documentation/documentation.md +++ b/dox/dev_guides/documentation/documentation.md @@ -9,19 +9,15 @@ This document provides practical guidenes for generation and editing of OCCT use @section OCCT_DM_SECTION_2 Prerequisites +In order to generate documentation, you need to have the following software installed. + Tcl/Tk Version 8.5 or 8.6: http://www.tcl.tk/software/tcltk/download.html Doxygen Version 1.8.4 or above: http://www.stack.nl/~dimitri/doxygen/download.html -MathJax (used for rendering math formulas in browser). -See \ref OCCT_DM_SECTION_A_9 paragraph for more detailed description. -The latest version: http://www.mathjax.org/download/ - -MiKTeX or equivalent tool (used for PDF document creation) - -Latest version: http://miktex.org/download +MiKTeX or equivalent tool (only needed for PDF document creation): http://miktex.org/download **Note**: to generate pdf documentation with MiKTeX you should execute gendoc.bat within MiKTeX environment (run gendoc.bat in MiKTeX command promt or update PATH for MiKTeX bin folder). Also in process of pdf generation @@ -32,6 +28,12 @@ MiKTeX can request you to download missing packages if MiKTeX was installed with If this option is set to "Yes", MiKTeX will download missing packages automatically. +MathJax is used for rendering math formulas in browser (HTML and CHM outputs): http://www.mathjax.org. + +By default MathJAX scripts and fonts are taken from http://cdn.mathjax.org/mathjax/latest and no instalation of MathJAX is necessary if Internet is accessible. +If you need to use OCCT documentation while offline, you can install local copy of MatJAX, see http://www.mathjax.org/download/. +See \ref OCCT_DM_SECTION_A_9 paragraph for more details on inserting math. + @section OCCT_DM_SECTION_2_1 Documentation Generation Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt: @@ -42,42 +44,26 @@ gendoc.bat options: * -pdf : To generate PDF files (cannot be used with -html); * -m=\ : Specifies list of articles to generate. If it is not specified, all files, mentioned in FILES.txt are processed; * -l=\ : Specifies the article caption for a single document; + * -mathjax=\ : Specifies path to non-default MathJAX installation * -h : Prints help message; * -v : Specifies the Verbose mode (info on all script actions is shown). -If you run the command without arguments (like example above) it will generate HTML documentation -for all articles are defined into FILES.txt. +If you run the command without arguments (like example above) it will generate HTML documentation for all articles defined in FILES.txt. **Note**: the generation process generates PDF files for each article, but in html case it generates common Html page with references to the ones. -For generation of specific article you need: - * have it's name with relative path (from \%OCCDIR\%/dox/ to the file) contained in FILES.txt - (is located into \%OCCDIR\%/dox/ directory). +For generation of specific article specify path to corresponding MarkDown file (paths relative to *dox* subfolder can be given), for instance: -@verbatim -devs_guid/documentation/documentation.md -@endverbatim - -where documentation .md is name of article and devs_guid/documentation/ is relative path of it - - * use this name with -m option in the generation process: - -@verbatim -% gendoc.bat -html -m=devs_guid/documentation/documentation.md -@endverbatim + % gendoc.bat -html -m=dev_guides/documentation/documentation.md -Multiple files are separated with comma: +Multiple files can be separated with comma: -@verbatim -% gendoc.bat -html -m=MD_FILE_1,MD_FILE_2 -@endverbatim + % gendoc.bat -html -m=MD_FILE_1,MD_FILE_2 -To sepcify a article name with -l option, use quotes to prevent incorrect interpretation of whitespaces: +To specify an article name with -l option, use quotes to prevent incorrect interpretation of whitespaces: -@verbatim -% gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document" -@endverbatim + % gendoc.bat -pdf -m=MD_FILE_1 -l="Label of MD_FILE_1 document" @section OCCT_DM_SECTION_3 Documentation Conventions @@ -426,33 +412,7 @@ The TOC in the PDF document will be generated automatically. @subsection OCCT_DM_SECTION_A_9 Formulas -Formulas within documents will be generated using MathJax tool. - -A developer has to specify these parameters in Doxyfile to enable support of MathJax in Doxygen: - - USE_MATHJAX = YES - MATHJAX_FORMAT = HTML-CSS - MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest - MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols - -To use MathJax tool with the HTML page, it's \ block has to contain - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html} - - - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First script configures MathJax to understand separator types and to left allign formulas. -The second script inserts reference to MathJax tool. -This tool will always be used when the HTML output will be shown. +Formulas within MarkDown documents can be defined using LaTeX syntax. Equations can be written by several ways: diff --git a/dox/occdoc.tcl b/dox/occdoc.tcl index 3c391b8d9e..417f4123be 100644 --- a/dox/occdoc.tcl +++ b/dox/occdoc.tcl @@ -20,7 +20,7 @@ proc OverviewDoc_DetectCasVersion {theCasRoot} { } # Generates Doxygen configuration file for Overview documentation -proc OverviewDoc_MakeDoxyfile {casDir outDir tagFileDir {doxyFileName} {generatorMode ""} DocFilesList verboseMode searchMode hhcPath} { +proc OverviewDoc_MakeDoxyfile {casDir outDir tagFileDir {doxyFileName} {generatorMode ""} DocFilesList verboseMode searchMode hhcPath mathjaxLocation} { set doxyFile [open $doxyFileName "w"] set casroot $casDir @@ -150,7 +150,7 @@ proc OverviewDoc_MakeDoxyfile {casDir outDir tagFileDir {doxyFileName} {generato puts $doxyFile "FORMULA_TRANSPARENT = YES" puts $doxyFile "USE_MATHJAX = YES" puts $doxyFile "MATHJAX_FORMAT = HTML-CSS" - puts $doxyFile "MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest" + puts $doxyFile "MATHJAX_RELPATH = ${mathjaxLocation}" } elseif { $generatorMode == "CHM_ONLY"} { puts $doxyFile "GENERATE_HTMLHELP = YES" @@ -162,7 +162,7 @@ proc OverviewDoc_MakeDoxyfile {casDir outDir tagFileDir {doxyFileName} {generato puts $doxyFile "FORMULA_TRANSPARENT = YES" puts $doxyFile "USE_MATHJAX = YES" puts $doxyFile "MATHJAX_FORMAT = HTML-CSS" - puts $doxyFile "MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest" + puts $doxyFile "MATHJAX_RELPATH = ${mathjaxLocation}" } elseif { $generatorMode == "PDF_ONLY"} { puts $doxyFile "GENERATE_HTMLHELP = NO" @@ -215,25 +215,26 @@ proc OverviewDoc_PrintHelpMessage {} { puts "\nUsage : occdoc \[-h\] \[-html\] \[-pdf\] \[-m=\] \[-l=\] \[-v\] \[-s\]" puts "" puts " Options are : " - puts " -html : To generate HTML files" - puts " (cannot be used with -pdf or -chm)" - puts " -pdf : To generate PDF files" - puts " (cannot be used with -html or chm)" - puts " -chm : To generate CHM files" - puts " (cannot be used with -html or pdf)" - puts " -hhc : To define path to hhc - chm generator" - puts " : is used with just -chm option" - puts " -m= : Specifies list of documents to generate." - puts " If it is not specified, all files, " - puts " mentioned in FILES.txt are processed." - puts " -l= : Specifies the document caption " - puts " for a single document" - puts " -h : Prints help message" - puts " -v : Specifies the Verbose mode" - puts " (info on all script actions is shown)" - puts " -s= : Specifies the Search mode of HTML documents." - puts " Can be: none | local | server | external | " - puts " : Can be used only with -html option" + puts " -html : To generate HTML files" + puts " (cannot be used with -pdf or -chm)" + puts " -pdf : To generate PDF files" + puts " (cannot be used with -html or chm)" + puts " -chm : To generate CHM files" + puts " (cannot be used with -html or pdf)" + puts " -hhc : To define path to hhc - chm generator" + puts " : is used with just -chm option" + puts " -m= : Specifies list of documents to generate." + puts " If it is not specified, all files " + puts " mentioned in FILES.txt are processed." + puts " -l= : Specifies the document caption " + puts " for a single document" + puts " -h : Prints help message" + puts " -v : Specifies the Verbose mode" + puts " (info on all script actions is shown)" + puts " -s= : Specifies the Search mode of HTML documents." + puts " Can be: none | local | server | external" + puts " : Can be used only with -html option" + puts " -mathjax= : To use local or alternative copy of MathJax" } # Parses command line arguments @@ -509,7 +510,7 @@ proc OverviewDoc_ProcessTex {{texFiles {}} {latexDir} verboseMode} { } # Main procedure for documents compilation -proc OverviewDoc_Main { {docfiles {}} generatorMode docLabel verboseMode searchMode hhcPath} { +proc OverviewDoc_Main { {docfiles {}} generatorMode docLabel verboseMode searchMode hhcPath mathjaxLocation} { set INDIR [file normalize [file dirname [info script]]] set CASROOT [file normalize [file dirname "$INDIR/../../"]] @@ -536,11 +537,23 @@ proc OverviewDoc_Main { {docfiles {}} generatorMode docLabel verboseMode searchM file delete -force $LATEXDIR } file mkdir $LATEXDIR + + # is MathJax HLink? + set mathjax_relative_location $mathjaxLocation + if { [file isdirectory "$mathjaxLocation"] == 1 } { + if { $generatorMode == "HTML_ONLY"} { + # related path + set mathjax_relative_location [relativePath $HTMLDIR $mathjaxLocation] + } elseif { $generatorMode == "CHM_ONLY"} { + # absolute path + set mathjax_relative_location [file normalize $mathjaxLocation] + } + } # Run tools to compile documents puts "[clock format [clock seconds] -format {%Y-%m-%d %H:%M}] Generating Doxyfile..." - OverviewDoc_MakeDoxyfile $CASROOT "$OUTDIR/overview" $TAGFILEDIR $DOXYFILE $generatorMode $docfiles $verboseMode $searchMode $hhcPath + OverviewDoc_MakeDoxyfile $CASROOT "$OUTDIR/overview" $TAGFILEDIR $DOXYFILE $generatorMode $docfiles $verboseMode $searchMode $hhcPath $mathjax_relative_location # Run doxygen tool if { $generatorMode == "HTML_ONLY"} { @@ -648,6 +661,38 @@ proc OverviewDoc_Main { {docfiles {}} generatorMode docLabel verboseMode searchM } } +proc relativePath {thePathFrom thePathTo} { + if { [file isdirectory "$thePathFrom"] == 0 } { + return "" + } + + set aPathFrom [file normalize "$thePathFrom"] + set aPathTo [file normalize "$thePathTo"] + + set aCutedPathFrom "${aPathFrom}/dummy" + set aRelatedDeepPath "" + + while { "$aCutedPathFrom" != [file normalize "$aCutedPathFrom/.."] } { + set aCutedPathFrom [file normalize "$aCutedPathFrom/.."] + # does aPathTo contain aCutedPathFrom? + regsub -all $aCutedPathFrom $aPathTo "" aPathFromAfterCut + if { "$aPathFromAfterCut" != "$aPathTo" } { # if so + if { "$aCutedPathFrom" == "$aPathFrom" } { # just go higher, for example, ./somefolder/someotherfolder + set aPathTo ".${aPathTo}" + } elseif { "$aCutedPathFrom" == "$aPathTo" } { # remove the last "/" + set aRelatedDeepPath [string replace $aRelatedDeepPath end end ""] + } + regsub -all $aCutedPathFrom $aPathTo $aRelatedDeepPath aPathToAfterCut + regsub -all "//" $aPathToAfterCut "/" aPathToAfterCut + return $aPathToAfterCut + } + set aRelatedDeepPath "$aRelatedDeepPath../" + + } + + return $thePathTo +} + # A command for User Documentation compilation proc occdoc {args} { # Programm options @@ -659,6 +704,9 @@ proc occdoc {args} { set SEARCH_MODE "none" set hhcPath "" + set mathjax_location "http://cdn.mathjax.org/mathjax/latest" + set mathjax_js_name "MathJax.js" + global available_docfiles global tcl_platform global args_names @@ -758,6 +806,19 @@ proc occdoc {args} { puts "Error in argument s" return } + } elseif {$arg_n == "mathjax"} { + if {![info exists args_values(pdf)]} { + set possible_mathjax_loc $args_values(mathjax) + if {[file exist [file join $possible_mathjax_loc $mathjax_js_name]]} { + set mathjax_location $args_values(mathjax) + puts "$mathjax_location" + } else { + puts "Warning: $mathjax_js_name isn't found in $possible_mathjax_loc." + puts " MathJax will be used from $mathjax_location" + } + } else { + puts "Info: MathJax is not used with pdf and will be ignored" + } } else { puts "\nWrong argument: $arg_n" OverviewDoc_PrintHelpMessage @@ -777,5 +838,5 @@ proc occdoc {args} { } # Start main activities - OverviewDoc_Main $DOCFILES $GEN_MODE $DOCLABEL $VERB_MODE $SEARCH_MODE $hhcPath + OverviewDoc_Main $DOCFILES $GEN_MODE $DOCLABEL $VERB_MODE $SEARCH_MODE $hhcPath $mathjax_location } -- 2.20.1