View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0032340 | Open CASCADE | OCCT:Documentation | public | 2021-04-29 13:01 | 2021-08-23 22:59 |
| Reporter | btokarev | Assigned To | bugmaster | ||
| Priority | normal | Severity | integration request | ||
| Status | closed | Resolution | fixed | ||
| Product Version | 7.5.0 | ||||
| Target Version | 7.6.0 | Fixed in Version | 7.6.0 | ||
| Summary | 0032340: OCCT Documentation - highlight C++ code snippets | ||||
| Description | C++ syntax highlighting is missing for multiple code examples through the documentation. All code snippets should be processed as presented in "Tutorials and Samples -> Tutorial". | ||||
| Steps To Reproduce | To verify the fix it is necessary to generate a new documentation from the updated .md files. | ||||
| Tags | No tags attached. | ||||
| Test case number | Not required | ||||
|
|
Syntax.png (41,954 bytes) |
|
|
Branch CR32340 has been created by btokarev. SHA-1: 93c9c1dc290e4238d8a5653c92cf055ba166e99c Detailed log of new commits: Author: btokarev Date: Thu Apr 29 13:28:10 2021 +0300 0032340: OCCT Documentation - highlight C++ code snippets Added missing {.cpp} markers to the first code block border for C++ code snippets; Extensive "~~~~~~~" code block borders are reduced to required minimum of "~~~~" (4); Removed obsolete space bars after code block borders. |
|
|
There are too many misinterpretations of source language in the patch for choosing syntax highlighter. It might be useful splitting a patch into smaller pieces to verify each domain carefully.
-~~~~~
+~~~~{.cpp}
Draw[]> testgrid
-~~~~~
+~~~~
...
-~~~~~
+~~~~{.cpp}
Draw[]> testgrid bugs caf,moddata*,xde
-~~~~~
+~~~~
...
>more occurrences<
All Draw> lines - are technically Tcl input, not C++. But I guess that Tcl highlighter is useless here too.
-~~~~~
+~~~~{.cpp}
git status -short
This is shell output, not C++.
-~~~~~
+~~~~{.cpp}
caf
mesh
offset
-~~~~~
+~~~~
...
-~~~~~~~~~~~~~~~~~
+~~~~{.cpp}
001 gridname1
002 gridname2
...
NNN gridnameN
-~~~~~~~~~~~~~~~~~
+~~~~
...
-~~~~~~~~~~~~~~~~~
+~~~~{.cpp}
001 basic
002 advanced
-~~~~~~~~~~~~~~~~~
+~~~~
These are no code at all - just a pre-formatted text. Please remove C++ highlighter.
-~~~~~
+~~~~{.cpp}
if { [isdraw result] } {
This is Tcl syntax.
-~~~~~
+~~~~{.cpp}
"Bnd_OBB": {
This is JSON syntax, not C++ (don't know if there is JSON highlighter, but maybe JavaScipt will work too).
-~~~~
+~~~~{.cpp}
<3D curve record 2> = "2" <_> <3D circle center> <_> <3D circle N> <_> <3D circle Dx> <_> <3D circle Dy> <_> <3D circle radius> <_\n>;
This is not a code to highlight.
### GLSL program:
-~~~~~{.fs}
+~~~~{.cpp}{.fs}
This is technically incorrect - GLSL is not C++. But I guess that produced highlighting looks fine and there is no GLSL highlighter in Doxygen anyway. |
|
|
Branch CR32340 has been updated by btokarev. SHA-1: 022b00a5c35fc58aa10dfd9a7a1eb03d6e66bf9c Detailed log of new commits: Author: btokarev Date: Thu Apr 29 17:41:25 2021 +0300 CR32340: OCCT Documentation - highlight C++ code snippets Removed excessive {.cpp} and {.tcl} marks related to using Draw, shell outputs and git. |
|
|
While researching the false appends of {.cpp} code markers to TCL code blocks I have discovered following: Several inclusions (<100) of {.cpp} were present in the documentation before applying the highlighting patch (mostly within Draw User guide); TCL syntax is not supported by Doxygen so {.tcl} code block markers are obsolete; Currently enabled highlighting misinterprets TCL comments (see example.png). I have researched available code block highlighters for Doxygen (see Syntax_demo.7z) to try and find any suitable substitution marker. My proposition here is to replace {.cpp} markers for TCL code blocks with any of following: {.d}, {.java} or {.php} as it seems to mimic TCL highlighting more accurate compared to {.cpp} markers. Another option is to fully remove misused markers. Requesting further course of action. I will continue working on this patch after the decision is made. |
|
|
Syntax_demo.7z (121,503 bytes) |
|
|
example.png (21,176 bytes) |
|
|
OK, lets try .php for Tcl code blocks for now. |
|
|
Branch CR32340 has been updated by btokarev. SHA-1: 420e41bd77f5311a2749a19284d47d80596b8024 Detailed log of new commits: Author: btokarev Date: Mon May 17 17:58:08 2021 +0300 0032340: OCCT Documentation - highlight C++ code snippets TCL code blocks are now highlighted with {.php} markers; Removed excessive {.cpp} highlighting markers appended to non-code blocks such as lists, reports and file content or structure examples; Minor fixes for tests.md and draw_test_harness.md (whitespace removal and structural fix for "Where:" in code examples). |
|
|
Please squash modifications into single commit and push as new branch CR32340_1 for review. |
|
|
Branch CR32340_1 has been created by btokarev. SHA-1: f0259be4a618199f619a96e965bb777a8550be77 Detailed log of new commits: Author: btokarev Date: Tue May 18 13:09:50 2021 +0300 0032340: OCCT Documentation - highlight C++ code snippets Squashed commits of following: 93c9c1dc290e4238d8a5653c92cf055ba166e99c 022b00a5c35fc58aa10dfd9a7a1eb03d6e66bf9c 420e41bd77f5311a2749a19284d47d80596b8024 Summary: Added {.cpp} highlighting markers to the C++ code blocks in documentation; Excessive tildes "~~~~~~~" in code block borders are reduced to required minimum of "~~~~" (4); Removed obsolete space bars after code block borders; TCL code blocks are now highlighted with {.php} markers; Removed excessive {.cpp} highlighting markers appended to non-code blocks such as lists, reports and file content or structure examples; Minor fixes for tests.md and draw_test_harness.md (whitespace removal and structural fix for "Where:" in code examples); Minimum HDD space for OCCT updated in introduction.md. |
|
|
Squashed commits of following:
93c9c1dc290e4238d8a5653c92cf055ba166e99c
022b00a5c35fc58aa10dfd9a7a1eb03d6e66bf9c
420e41bd77f5311a2749a19284d47d80596b8024
This is irrelevant information which should not be included into commit description. |
|
|
Branch CR32340_2 has been created by kgv. SHA-1: d06c18b917ecfe3e35bc9b6ac91b29b84d7ab843 Detailed log of new commits: Author: btokarev Date: Tue May 18 13:09:50 2021 +0300 0032340: OCCT Documentation - highlight C++ code snippets Added {.cpp} highlighting markers to the C++ code blocks in documentation; Excessive tildes "~~~~~~~" in code block borders are reduced to required minimum of "~~~~" (4); Removed obsolete space bars after code block borders; TCL code blocks are now highlighted with {.php} markers; Removed excessive {.cpp} highlighting markers appended to non-code blocks such as lists, reports and file content or structure examples; Minor fixes for tests.md and draw_test_harness.md (whitespace removal and structural fix for "Where:" in code examples); Minimum HDD space for OCCT updated in introduction.md. |
|
|
Please raise the patch - OCCT: branch CR32340_2. |
|
|
Combination - OCCT branch : IR-2021-05-21 master SHA - 2aa0a6991da6f767c2a6a4c1d6d720fee35867ce a87b7ddc8cb44606b91e3f37113847c3f5f50fdc Products branch : IR-2021-05-21 SHA - e89cefb48fe77db69215a5124b453f69d9db404b was compiled on Linux, MacOS and Windows platforms and tested in optimize mode. Number of compiler warnings: No new/fixed warnings Regressions/Differences/Improvements: No regressions/differences CPU differences: Debian80-64: OCCT Total CPU difference: 17862.650000000373 / 17879.470000000332 [-0.09%] Products Total CPU difference: 11535.410000000107 / 11557.880000000083 [-0.19%] Windows-64-VC14: OCCT Total CPU difference: 19361.25 / 19400.171875 [-0.20%] Products Total CPU difference: 12920.28125 / 12880.234375 [+0.31%] Image differences : No differences that require special attention Memory differences : No differences that require special attention |
|
|
Branch CR32340 has been deleted by kgv. SHA-1: 420e41bd77f5311a2749a19284d47d80596b8024 |
|
|
Branch CR32340_1 has been deleted by kgv. SHA-1: f0259be4a618199f619a96e965bb777a8550be77 |
|
|
Branch CR32340_2 has been deleted by kgv. SHA-1: d06c18b917ecfe3e35bc9b6ac91b29b84d7ab843 |
|
occt: master 77d94fd1 2021-05-18 10:09:50 Committer: bugmaster Details Diff |
0032340: OCCT Documentation - highlight C++ code snippets Added {.cpp} highlighting markers to the C++ code blocks in documentation; Excessive tildes "~~~~~~~" in code block borders are reduced to required minimum of "~~~~" (4); Removed obsolete space bars after code block borders; TCL code blocks are now highlighted with {.php} markers; Removed excessive {.cpp} highlighting markers appended to non-code blocks such as lists, reports and file content or structure examples; Minor fixes for tests.md and draw_test_harness.md (whitespace removal and structural fix for "Where:" in code examples); Minimum HDD space for OCCT updated in introduction.md. |
Affected Issues 0032340 |
|
| mod - dox/build/build_occt/building_occt.md | Diff File | ||
| mod - dox/contribution/coding_rules.md | Diff File | ||
| mod - dox/contribution/git_guide/git_guide.md | Diff File | ||
| mod - dox/contribution/tests/tests.md | Diff File | ||
| mod - dox/debug/debug.md | Diff File | ||
| mod - dox/introduction/introduction.md | Diff File | ||
| mod - dox/samples/ocaf.md | Diff File | ||
| mod - dox/samples/ocaf_func.md | Diff File | ||
| mod - dox/specification/boolean_operations/boolean_operations.md | Diff File | ||
| mod - dox/specification/brep_format.md | Diff File | ||
| mod - dox/tutorial/tutorial.md | Diff File | ||
| mod - dox/upgrade/upgrade.md | Diff File | ||
| mod - dox/user_guides/draw_test_harness/draw_test_harness.md | Diff File | ||
| mod - dox/user_guides/foundation_classes/foundation_classes.md | Diff File | ||
| mod - dox/user_guides/iges/iges.md | Diff File | ||
| mod - dox/user_guides/inspector/inspector.md | Diff File | ||
| mod - dox/user_guides/mesh/mesh.md | Diff File | ||
| mod - dox/user_guides/modeling_algos/modeling_algos.md | Diff File | ||
| mod - dox/user_guides/modeling_data/modeling_data.md | Diff File | ||
| mod - dox/user_guides/ocaf/ocaf.md | Diff File | ||
| mod - dox/user_guides/shape_healing/shape_healing.md | Diff File | ||
| mod - dox/user_guides/step/step.md | Diff File | ||
| mod - dox/user_guides/vis/vis.md | Diff File | ||
| mod - dox/user_guides/visualization/visualization.md | Diff File | ||
| mod - dox/user_guides/xde/xde.md | Diff File | ||
| Date Modified | Username | Field | Change |
|---|---|---|---|
| 2021-04-29 13:01 | btokarev | New Issue | |
| 2021-04-29 13:01 | btokarev | Assigned To | => btokarev |
| 2021-04-29 13:01 | btokarev | File Added: Syntax.png | |
| 2021-04-29 13:02 | btokarev | Relationship added | child of 0031896 |
| 2021-04-29 13:27 | git | Note Added: 0100662 | |
| 2021-04-29 13:31 | btokarev | Steps to Reproduce Updated | |
| 2021-04-29 13:32 | btokarev | Assigned To | btokarev => abv |
| 2021-04-29 13:32 | btokarev | Status | new => resolved |
| 2021-04-29 13:39 | btokarev | Assigned To | abv => inv |
| 2021-04-29 13:42 | btokarev | Assigned To | inv => kgv |
| 2021-04-29 13:52 | kgv | Note Added: 0100664 | |
| 2021-04-29 13:52 | kgv | Assigned To | kgv => btokarev |
| 2021-04-29 13:52 | kgv | Status | resolved => assigned |
| 2021-04-29 13:53 | kgv | Note Edited: 0100664 | |
| 2021-04-29 13:54 | kgv | Note Edited: 0100664 | |
| 2021-04-29 13:54 | kgv | Product Version | 7.6.0 => 7.5.0 |
| 2021-04-29 17:41 | git | Note Added: 0100670 | |
| 2021-05-06 14:43 | btokarev | Note Added: 0100796 | |
| 2021-05-06 14:44 | btokarev | File Added: Syntax_demo.7z | |
| 2021-05-06 14:45 | btokarev | File Added: example.png | |
| 2021-05-11 12:43 | kgv | Note Added: 0100874 | |
| 2021-05-17 17:58 | git | Note Added: 0101109 | |
| 2021-05-17 18:01 | btokarev | Assigned To | btokarev => kgv |
| 2021-05-17 18:01 | btokarev | Status | assigned => resolved |
| 2021-05-17 20:18 | kgv | Note Added: 0101116 | |
| 2021-05-17 20:18 | kgv | Assigned To | kgv => btokarev |
| 2021-05-17 20:18 | kgv | Status | resolved => assigned |
| 2021-05-18 13:09 | git | Note Added: 0101139 | |
| 2021-05-18 13:12 | btokarev | Assigned To | btokarev => kgv |
| 2021-05-18 13:12 | btokarev | Status | assigned => resolved |
| 2021-05-18 15:05 | kgv | Note Added: 0101145 | |
| 2021-05-18 15:16 | git | Note Added: 0101147 | |
| 2021-05-18 15:16 | kgv | Note Added: 0101148 | |
| 2021-05-18 15:16 | kgv | Assigned To | kgv => bugmaster |
| 2021-05-18 15:16 | kgv | Status | resolved => reviewed |
| 2021-05-22 12:24 | bugmaster | Note Added: 0101253 | |
| 2021-05-22 12:24 | bugmaster | Status | reviewed => tested |
| 2021-05-22 12:30 | bugmaster | Test case number | => Not required |
| 2021-05-22 12:38 | bugmaster | Changeset attached | => occt master 77d94fd1 |
| 2021-05-22 12:38 | bugmaster | Status | tested => verified |
| 2021-05-22 12:38 | bugmaster | Resolution | open => fixed |
| 2021-08-23 22:59 | git | Note Added: 0103360 | |
| 2021-08-23 22:59 | git | Note Added: 0103361 | |
| 2021-08-23 22:59 | git | Note Added: 0103362 |
