Hi, Le sam. 20 nov. 2021 à 22:08, Sebastian Kuzminsky <[email protected]> a écrit :
> > Unless there's a strong reason to, please avoid making whitespace > changes (such as deleting newline characters to combine short lines of > "flowed" or "word-wrapped" text into a single long line). > > There are a couple of reasons for this: > > Spurious whitespace changes make it harder to track changes over time. > My proposal would make them far less than spurious ! 😅 > The git revision control system is line-oriented, which means that lines > that fit on a screen are much easier to work with than lines that are so > long that they wrap, or that you have to scroll the screen to see the > end of them. > I'm all in for that as far as code is concerned, no argument ! > This is part of our "best practices for contributing" guidelines: > > > http://linuxcnc.org/docs/devel/html/code/contributing-to-linuxcnc.html#_follow_the_style_of_the_surrounding_code > > That said, if there's a compelling argument for why this situation is > special and the usual norms should be reconsidered, I'd be happy to hear > it. > Perfectly agree with these guidelines too, and would conform to it pushing the proposed changes in separate commits... That said, as far as I believe documentation should be treated and managed as code, it is not code per se. And it comforts me that the pointed guideline mentions semantics because this is what my proposal is all about ! Indeed, using fixed line width for natural language has two major flaws: * It breaks text (vs code) formating semantics, at least for tools unaware of such convention (see this screencap of our docs in Crowdin https://i.imgur.com/GnY3H7s.png); * It makes side by side comparison of several languages much more difficult because some are more/less "wordy" than others and fixed line width breaks file structure correspondence (see this other screencap https://i.imgur.com/z0MOKOH.png). Not having semantically sound documentation source files structure ties us to specific high level tools such as po4a, which happily seem (to be double checked) to understand this practice (and asciidoc syntax) and rebuilds sentences to generate pot/po files. See this cap https://i.imgur.com/meXNY7u.png where the same sentence as in the previous picture is actually recognised as a single block, whereas it is split on several lines in source. Also, Git really doesn't care if lines are 72/80 characters long or several hundreds, only our programmer eyes do. Finally, documentation source files should be formatted for their users, who are translators, who should care about languages in all their specificities, including structure. All in all we are on for a major rework, I believe that this would raise our overall documentation quality, and that this is the good time for such a change. TY Jé _______________________________________________ Emc-developers mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/emc-developers
