From 19e92c9d11967d29cd263d548021260dae36eeb0 Mon Sep 17 00:00:00 2001 From: jean-pierre charras Date: Sun, 29 Dec 2019 09:53:39 +0100 Subject: [PATCH] Eeschema: replace dialog_bom_help.html by dialog_bom_help.md The .md files are smaller and translatable. --- .gitignore | 2 +- eeschema/CMakeLists.txt | 19 +- eeschema/dialogs/dialog_bom.cpp | 10 +- eeschema/dialogs/dialog_bom_help.html | 286 -------------------------- eeschema/dialogs/dialog_bom_help.md | 143 +++++++++++++ 5 files changed, 160 insertions(+), 300 deletions(-) delete mode 100644 eeschema/dialogs/dialog_bom_help.html create mode 100644 eeschema/dialogs/dialog_bom_help.md diff --git a/.gitignore b/.gitignore index 0f2ab62bcf..d6569777e8 100644 --- a/.gitignore +++ b/.gitignore @@ -17,7 +17,7 @@ eeschema/cmp_library_lexer.h eeschema/cmp_library_keywords.* eeschema/dialogs/dialog_bom_cfg_keywords.cpp eeschema/dialogs/dialog_bom_cfg_lexer.h -eeschema/dialogs/dialog_bom_help_html.h +eeschema/dialogs/dialog_bom_help_md.h eeschema/template_fieldnames_keywords.* eeschema/template_fieldnames_lexer.h pcbnew/pcb_plot_params_keywords.cpp diff --git a/eeschema/CMakeLists.txt b/eeschema/CMakeLists.txt index d10700c962..4b6353077b 100644 --- a/eeschema/CMakeLists.txt +++ b/eeschema/CMakeLists.txt @@ -277,21 +277,21 @@ else() set( EESCHEMA_RESOURCES eeschema.rc ) endif() -# Create a C++ compilable string initializer containing html text into a *.h file: +# Create a C++ compilable string initializer containing markdown text into a *.h file: add_custom_command( - OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help_html.h + OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help_md.h COMMAND ${CMAKE_COMMAND} - -DinputFile=${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help.html - -DoutputFile=${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help_html.h - -P ${CMAKE_MODULE_PATH}/Html2C.cmake - DEPENDS ${CMAKE_MODULE_PATH}/Html2C.cmake ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help.html - COMMENT "creating ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help_html.h - from ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help.html" + -DinputFile=${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help.md + -DoutputFile=${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help_md.h + -P ${CMAKE_MODULE_PATH}/markdown2C.cmake + DEPENDS ${CMAKE_MODULE_PATH}/markdown2C.cmake ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help.md + COMMENT "creating ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help_md.h + from ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help.md" ) set_source_files_properties( dialogs/dialog_bom.cpp PROPERTIES - OBJECT_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help_html.h + OBJECT_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/dialogs/dialog_bom_help_md.h ) if( APPLE ) @@ -354,6 +354,7 @@ target_include_directories( eeschema_kiface PUBLIC target_link_libraries( eeschema_kiface common sexpr + markdown_lib ${wxWidgets_LIBRARIES} ${GDI_PLUS_LIBRARIES} ) diff --git a/eeschema/dialogs/dialog_bom.cpp b/eeschema/dialogs/dialog_bom.cpp index 518c0bdd33..d012ab00ed 100644 --- a/eeschema/dialogs/dialog_bom.cpp +++ b/eeschema/dialogs/dialog_bom.cpp @@ -42,6 +42,7 @@ #include #include #include +#include // for _HKI definition used in dialog_bom_help_md.h #include @@ -50,8 +51,8 @@ static constexpr wxChar BOM_TRACE[] = wxT( "BOM_GENERATORS" ); static constexpr wxChar BOM_GENERATORS_KEY[] = wxT( "bom_plugins" ); static constexpr wxChar BOM_GENERATOR_SELECTED_KEY[] = wxT( "bom_plugin_selected" ); -static const char* s_bomHelpInfo = -#include +wxString s_bomHelpInfo = +#include ; using namespace T_BOMCFG_T; // for the BOM_CFG_PARSER parser and its keywords @@ -594,8 +595,9 @@ void DIALOG_BOM::OnHelp( wxCommandEvent& event ) HTML_MESSAGE_BOX help_Dlg( this, _( "Bill of Material Generation Help" ) ); help_Dlg.SetDialogSizeInDU( 500, 350 ); - wxString msg = FROM_UTF8( s_bomHelpInfo ); - help_Dlg.m_htmlWindow->AppendToPage( msg ); + wxString html_txt; + ConvertMarkdown2Html( wxGetTranslation( s_bomHelpInfo ), html_txt ); + help_Dlg.m_htmlWindow->AppendToPage( html_txt ); help_Dlg.ShowModal(); } diff --git a/eeschema/dialogs/dialog_bom_help.html b/eeschema/dialogs/dialog_bom_help.html deleted file mode 100644 index 174462e139..0000000000 --- a/eeschema/dialogs/dialog_bom_help.html +++ /dev/null @@ -1,286 +0,0 @@ - - - - - kicad help - - - - - - - - - - - - - - - - - - -

1 - -Full documentation:

-

-The -Eeschema documentation describes -this intermediate netlist and gives examples
See -http://docs.kicad-pcb.org/stable/en/eeschema.html#creating-customized-netlists-and-bom-files

-

2 - The intermediate Netlist File

-

-BOM -files (and netlist files) can be created from an Intermediate netlist -file created by Eeschema.

-

-This -file uses XML syntax and is called the intermediate netlist. The -intermediate netlist includes a large amount of data about your board -and because of this, it can be used with post-processing to create a -BOM or other reports.

-

-Depending -on the output (BOM or netlist), different subsets of the complete -Intermediate Netlist file will be used in the post-processing.

-

3 - Conversion to a new format

-

-By -applying a post-processing filter to the Intermediate netlist file -you can generate foreign netlist files as well as BOM files. Because -this conversion is a text to text transformation.

-

-this -post-processing filter can be written using Python, XSLT, -or any other tool capable of taking XML as input.

-

-XSLT -itself is a XML language very suitable for XML transformations. There -is a free program called xsltproc -that -you can download and install. The -xsltproc -program can be used to read the Intermediate XML netlist input file, -apply a -style-sheet to transform the input, and save the results in an output -file. Use of xsltproc requires a style-sheet file using XSLT -conventions. The full conversion process is handled -by -Eeschema, after it is configured once to run xsltproc in a specific -way.

-

-A -Python script is somewhat more easy to create.

-

4 - Initialization of the dialog window

-

-You -should add a new pluging (a script) in plugin list by clicking on the -Add Plugin button.

-

4.1 - Plugin Configuration Parameters

-

-The -Eeschema plug-in configuration dialog requires the following -information:

-
    -
  • -

    - The - title: for instance, the name of the netlist format.

    -
  • -

    - The - command line to launch the converter (usually a script).

    -
-

-Note (Windows only):

-

-By default, command line runs with hidden console window and output is redirected to "Plugin info" field. To show the window of the running command, set the checkbox "Show console window".

-

-Once -you click on the generate button the following will happen:

-
    -
  1. -

    - Eeschema - creates an intermediate netlist file *.xml, for instance test.xml.

    -
  2. -

    - Eeschema - runs the script from the command line to create the final output - file.

    -
-

4.2 - Generate netlist files with the command -line

-

-Assuming -we are using the program xsltproc.exe -to -apply the sheet style to the intermediate file, xsltproc.exe -is -executed with the following command.

-

-xsltproc.exe --o < output filename > < style-sheet filename > < -input XML file to convert >

-

-On -Windows the command line is the following.
f:/kicad/bin/xsltproc.exe --o “%O” f:/kicad/bin/plugins/myconverter.xsl “%I”

-

-On -Linux the command becomes as following.
xsltproc -o “%O” -/usr/local/kicad/bin/plugins/myconverter .xsl “%I”
where -myconverter.xsl -is -the style-sheet that you are applying.

-

-Do -not forget the double quotes -around -the file names, this allows them to have spaces after the -substitution by Eeschema.

-

-If -a Python script is used, the command line is something like -(depending on the Python script):

-

-python -f:/kicad/bin/plugins/bom-in-python/myconverter.py -“%I”“%O”
or
python -/usr/local/kicad/bin/plugins/bom-in-python/myconverter .xsl “%I” -“%O” -

-

-The -command line format accepts parameters for filenames:

-

-The -supported formatting parameters are.

-
    -
  • -

    - %B - => base filename of selected output file, minus path and extension.

    -
  • -

    - %P - => project directory, without name and without trailing '/'.

    -
  • -

    - %I - => complete filename and path of the temporary input file - (the intermediate net file).

    -
  • -

    - %O - => complete filename and path (but without extension) of the user - chosen output file.

    -
-

-%I -will be replaced by the actual intermediate file name(usually -the full root sheet filename with extension “.xml”)
%O -will -be replaced by the actual output file name (the full root sheet -filename minus extension).
%B -will -be replaced by the actual output short file name -(the -short root sheet filename minus extension).
%P -will -be replaced by the actual current project path.

-

4.3 - Command line format:

-

4.3.1 - Remark:

-

-Most -of time, the created file must have an extension, depending on its -type.
Therefore you have to add to the option %O the -right file extension.

-

-For -instance:

-
    -
  • -

    - %O.csv - to create a .csv file (comma separated value file).

    -
  • -

    - %O.html - to create a .html file.

    -
  • -

    - %O.bom - to create a .bom file.

    -
-

4.3.2 Example for xsltproc:

-

-The -command line format for xsltproc is the following:
< path of -xsltproc > xsltproc -< xsltproc parameters >

-

-On -Windows:
f:/kicad/bin/xsltproc.exe -o “%O.bom” -f:/kicad/bin/plugins/netlist_form_pads-pcb.xsl “%I”

-

-On -Linux:
xsltproc -o “%O.bom” -/usr/local/kicad/bin/plugins/netlist_form_pads-pcb.xsl “%I”

-

-The -above examples assume -xsltproc -is installed on your PC under Windows xsl -exe -files -located in kicad/binplugins/.

-

-
- -

-

4.3.3 Example for -python scripts:

-

-The -command line format for python is something like:
python -< -script file name > < input filename > < -output filename >

-

-On -Windows:
python.exe f:/kicad/bin/plugins -/bom-in-python/my_python_script.py “%I” -“%O.html”

-

-On -Linux:
python /usr/local/kicad/bin/plugins -/bom-in-python/my_python_script.py “%I” -“%O.csv”

-

-Assuming -python is installed on your PC, and python scripts are located in -kicad/bin/plugins /bom-in-python/.

-

-
- -

- - diff --git a/eeschema/dialogs/dialog_bom_help.md b/eeschema/dialogs/dialog_bom_help.md new file mode 100644 index 0000000000..6153ab6aa6 --- /dev/null +++ b/eeschema/dialogs/dialog_bom_help.md @@ -0,0 +1,143 @@ +# 1 - Full documentation + +The Eeschema documentation (*eeschema.html*) describes this intermediate netlist and gives examples(chapter ***creating customized netlists and bom files***). + +# 2 - The intermediate Netlist File + +BOM files (and netlist files) can be created from an *Intermediate netlist file* created by Eeschema. + +This file uses XML syntax and is called the intermediate netlist. The intermediate netlist includes a large amount of data about your board and because of this, it can be used with post-processing to create a BOM or other reports. + +Depending on the output (BOM or netlist), different subsets of the complete Intermediate Netlist file will be used in the post-processing. + +# 3 - Conversion to a new format + +By applying a post-processing filter to the Intermediate netlist file you can generate foreign netlist files as well as BOM files. Because this conversion is a text to text transformation, this post-processing filter can be written using *Python*, *XSLT*, or any other tool capable of taking XML as input. + +XSLT itself is a XML language suitable for XML transformations. There is a free program called `xsltproc` that you can download and install. The `xsltproc` program can be used to read the Intermediate XML netlist input file, apply a style-sheet to transform the input, and save the results in an output file. Use of `xsltproc` requires a style-sheet file using XSLT conventions. The full conversion process is handled by Eeschema, after it is configured once to run `xsltproc` in a specific way. + +A Python script is somewhat more easy to create. + +# 4 - Initialization of the dialog window + +You should add a new plugin (a script) in the plugin list by clicking on the Add Plugin button. + +## 4.1 - Plugin Configuration Parameters + +The Eeschema plug-in configuration dialog requires the following information: + + * The title: for instance, the name of the netlist format. + * The command line to launch the converter (usually a script). + +***Note (Windows only):*** +*By default, the command line runs with hidden console window and output is redirected to "Plugin info" field. To show the window of the running command, set the checkbox "Show console window".* + +Once you click on the generate button the following will happen: + +1. Eeschema creates an intermediate netlist file \*.xml, for instance `test.xml`. +2. Eeschema runs the script from the command line to create the final output file. + +## 4.2 - Generate netlist files with the command line + +Assuming we are using the program `xsltproc.exe` to apply the sheet style to the intermediate file, `xsltproc.exe` is executed with the following command. + +``` +xsltproc.exe -o +``` + +On Windows the command line is the following. + +``` +f:/kicad/bin/xsltproc.exe -o "%O" f:/kicad/bin/plugins/myconverter.xsl "%I" +``` + +On Linux the command becomes as following. + +``` +xsltproc -o "%O" /usr/local/kicad/bin/plugins/myconverter .xsl "%I" +``` +where `myconverter.xsl` is the style-sheet that you are applying. + +Do not forget the double quotes around the file names, this allows them to have spaces after the substitution by Eeschema. + +If a Python script is used, the command line is something like (depending on the Python script): + +``` +python f:/kicad/bin/plugins/bom-in-python/myconverter.py "%I" "%O" +``` + +or + +``` +python /usr/local/kicad/bin/plugins/bom-in-python/myconverter .xsl "%I" "%O" +``` + +The command line format accepts parameters for filenames. The supported formatting parameters are: + + * `%B`: base filename of selected output file, minus path and extension. + * `%P`: project directory, without name and without trailing '/'. + * `%I`: complete filename and path of the temporary input file +(the intermediate net file). + * `%O`: complete filename and path (but without extension) of the user +chosen output file. + +`%I` will be replaced by the actual intermediate file name (usually the full root sheet filename with extension ".xml"). +`%O` will be replaced by the actual output file name (the full root sheet filename minus extension). +`%B` will be replaced by the actual output short file name (the short root sheet filename minus extension). +`%P` will be replaced by the actual current project path. + +## 4.3 - Command line format: + +### 4.3.1 - Remark: + +Most of time, the created file must have an extension, depending on its type. +Therefore you have to add to the option ***%O*** the right file extension. + +For instance: + + * **%O.csv** to create a .csv file (comma separated value file). + * **%O.htm** to create a .html file. + * **%O.bom** to create a .bom file. + +### 4.3.2 Example for xsltproc: + +The command line format for xsltproc is the following: + +``` + xsltproc +``` + +On Windows: +``` +f:/kicad/bin/xsltproc.exe -o "%O.bom" f:/kicad/bin/plugins/netlist_form_pads-pcb.xsl "%I" +``` + +On Linux: +``` +xsltproc -o "%O.bom" /usr/local/kicad/bin/plugins/netlist_form_pads-pcb.xsl "%I" +``` + +The above examples assume `xsltproc` is installed on your PC under Windows and xsl files located in `/kicad/bin/plugins/`. + + +### 4.3.3 Example for Python scripts: + +Assuming python is installed on your PC, and python scripts are located in + + `/kicad/bin/plugins/bom-in-python/`, + +the command line format for python is something like: + +``` +python