FreeCAD icon indicating copy to clipboard operation
FreeCAD copied to clipboard

Published 20 hours ago • verified publisher icon FreeCAD

[Problem] Whitespace/Indentation uniformity issues in `src/Mod/Part/App/Geom2d` XML (API) files

Open luzpaz opened this issue 1 year ago • 16 comments

Is there an existing issue for this?

  • [X] I have searched the existing issues

Problem description

The XML files in https://github.com/FreeCAD/FreeCAD/tree/master/src/Mod/Part/App/Geom2d have non-uniform whitespace.

4 spaced indentation

https://github.com/FreeCAD/FreeCAD/blob/4293c4a65b0e69975dcdbbf68c80d8019a4f850d/src/Mod/Part/App/Geom2d/ArcOfCircle2dPy.xml#L1-L31

  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/ArcOfConic2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/ArcOfEllipse2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/ArcOfHyperbola2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/ArcOfParabola2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/Circle2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/Conic2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/Geometry2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/Line2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/Line2dSegmentPy.xml

Tabbed space (or 8 spaced) indentation example

https://github.com/FreeCAD/FreeCAD/blob/4293c4a65b0e69975dcdbbf68c80d8019a4f850d/src/Mod/Part/App/Geom2d/Parabola2dPy.xml#L1-L42

  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/BSplineCurve2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/BezierCurve2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/Curve2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/Ellipse2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/Hyperbola2dPy.xml
  • https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/Geom2d/OffsetCurve2dPy.xml

Full version info

Current v0.22 master

Subproject(s) affected?

Part

Anything else?

No response

Code of Conduct

  • [X] I agree to follow this project's Code of Conduct

luzpaz avatar Sep 19 '23 10:09 luzpaz

What is the official linting style of the FreeCAD API documentation ?

luzpaz avatar Sep 22 '23 11:09 luzpaz

@chennes is this something mentioned in the Developer handbook ?

luzpaz avatar Sep 23 '23 01:09 luzpaz

Hey @luzpaz are you currently working on this issue?

johnmichaeldnichols avatar Sep 26 '23 01:09 johnmichaeldnichols

@johnmichaeldnichols nope :smile:
Feel free to jump in!
Currently, waiting on guidelines for what indentation is preferred.

CC @chennes

luzpaz avatar Sep 26 '23 11:09 luzpaz

@wwmayer what is the agreed upon indentation format for the .xml documentation ?

luzpaz avatar Sep 28 '23 00:09 luzpaz

I don't know if this is officially documented but I vote to apply the same indentation rules as for our C++ or Python code: 4 spaces, no tabs

wwmayer avatar Sep 28 '23 08:09 wwmayer

@chennes @yorikvanhavre please weigh-in

luzpaz avatar Sep 28 '23 13:09 luzpaz

Agreed, 4 spaces, no tabs. Note that I think XML auto formatters are likely to give us headaches in the *Py.xml files, where we have many docstrings that won't use the expected indentation. So it's an area we will want to take care with if we decide to go with the automatic formatters.

chennes avatar Sep 28 '23 20:09 chennes

How to proceed here ?

luzpaz avatar Oct 03 '23 14:10 luzpaz

@luzpaz how to approach here ? Could you help.

RohanMishra315 avatar Oct 28 '23 11:10 RohanMishra315

I haven't found a utility to do the XML formatting as we want it. There is xmllint but it uses only two spaces. So, I have written our own utility: https://github.com/FreeCAD/FreeCAD/pull/11219

wwmayer avatar Oct 28 '23 13:10 wwmayer

@wwmayer sorry to ping but in that case how does it affect this ticket ?

luzpaz avatar Apr 23 '24 15:04 luzpaz

The utility will replace all tabs with spaces and uses 4 spaces for the indentations. So, exactly this what the ticket is about.

wwmayer avatar Apr 23 '24 15:04 wwmayer

@wwmayer yea, that's what I figured. Thanks for the clarification. Any idea when the utility will be run on the codebase ?

luzpaz avatar Apr 23 '24 15:04 luzpaz

Is the plan to run the utility before 1.0 release ?

luzpaz avatar Apr 27 '24 12:04 luzpaz

Yes, we can do that.

wwmayer avatar Apr 27 '24 19:04 wwmayer

I was looking for an easy project and saw this one, and saw that it was still undone, so I did it. I only checked the *.xml files in the named directory, and only repaired the ones with problems. So if wwmayer wants to run his XML Repair Tool on all XML files everywhere, he can still do that, otherwise he is now freed up for more important work. PR to follow soon. Thanks.

KimK avatar Jul 02 '24 11:07 KimK