MantisBT
Mantis Bug Tracker Workflow

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0032340Open CASCADE[OCCT] OCCT:Documentationpublic2021-04-29 13:012021-05-11 12:43
Reporterbtokarev 
Assigned Tobtokarev 
PrioritynormalSeverityintegration request 
StatusassignedResolutionopen 
PlatformOSOS Version
Product Version[OCCT] 7.5.0 
Target Version[OCCT] 7.6.0*Fixed in Version 
Summary0032340: OCCT Documentation - highlight C++ code snippets
DescriptionC++ 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 ReproduceTo verify the fix it is necessary to generate a new documentation from the updated .md files.
TagsNo tags attached.
Test case number
Attached Filespng file icon Syntax.png (41,954 bytes) 2021-04-29 13:01
7z file icon Syntax_demo.7z (121,503 bytes) 2021-05-06 14:44
png file icon example.png (21,176 bytes) 2021-05-06 14:45

- Relationships
child of 0031896newbtokarev Documentation - Proofreading User manual 

-  Notes
(0100662)
git (administrator)
2021-04-29 13:27

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.
(0100664)
kgv (developer)
2021-04-29 13:52
edited on: 2021-04-29 13:54

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.

(0100670)
git (administrator)
2021-04-29 17:41

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.

(0100796)
btokarev (developer)
2021-05-06 14:43

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.
(0100874)
kgv (developer)
2021-05-11 12:43

OK, lets try .php for Tcl code blocks for now.

- Issue History
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 View Revisions
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 View Revisions
2021-04-29 13:54 kgv Note Edited: 0100664 View Revisions
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


Copyright © 2000 - 2021 MantisBT Team
Powered by Mantis Bugtracker