search

pgf-tikz / pgf

A Portable Graphic Format for TeX
https://pgf-tikz.github.io/
1.14k stars 108 forks source link

Proposition: changing old syntax for circle and ellipse to new in manual #999

Open KZiemian opened 3 years ago

KZiemian commented 3 years ago

Version: 3.1.9

I recently read in manual that syntax for drawing of circle \draw (0,0) circle (10pt); is valid, but one should use new form. \draw (0,0) circle [radius=10pt]; The same for ellipse.

I personally try to avoid first form, since its more cryptic, but it is still very popular in various code snippets that you can find on web. Also, you can find it in manual itself, like at the beginning of the section "2.14 Shading" (part of "Tutorial: A Picture for Karl’s Students", page 39 in PDF of v. 3.1.8b), when we have: \tikz \shade (0,0) rectangle (2,1) (3,0.5) circle (.5cm);

I don't know how development of PGF/TikZ works and I don't waste developers time with unneeded PR with few dozens entries, so I want propose it first here. If it is desirable I can look through manual and replace every place when I find old syntax for circle or ellipse with new, always checking if after copy-past produce desired result.

If you want me to due that, I only need to ask, should I edit .tex files in GitHub pgf/doc/generic/pgf/text-en/ or somewhere else. This may be silly question, but in the past I was changing on GitHub documentation in files .md, when true documentation was in other format, from which .md files were generated. I don' want make this blunder again.

If some other code should be updated I can try do it also, but to this moment I found in manual information about circle and ellipse.

hmenke commented 3 years ago

Don't bother. \draw ... circle (...) is fully supported and will always be supported in the future. It is way too popular to ever be deprecated or removed.

Mo-Gul commented 3 years ago

I (personally) find this a good idea. Of course long-term users might still use the old syntax. But changing the remaining instances of the old syntax to the new one might help that new users as often as possible see the new syntax and thus get used to it.

KZiemian commented 3 years ago

My way of thinking is along the line of @Mo-Gul, since I'm a bit picky about code style. Since I consider the manual the canon of code style for PGF/TikZ using in all code examples recommended version can change habits of new users. Or people like me, who always want follow the best practices when writing code.

Also, you can hardly find official manuals as useful and user friendly as this of PGF/TikZ. Since mistakes and "legacy code" seems to be unavoidable in 1300 pages document, I want to help improve it in any place I can. When I read it I make a list of possible typos and mistakes, but since I'm not enough versed in PGF/TikZ and I don't want to waste time of maintainers, I don't make PR untile I'm sure that this is a mistake, not my ignorance in the play.

My offer is still open.

muzimuzhi commented 3 years ago

I support to keep the current behavior, at least for all 3.y.z versions. Note syntaxes circle (<radius>) and ellipse (<x radius> and <y radius>) should be changed at the same time.