Hi Jakub, On 06/11/2020 18:26, Jakub Narębski wrote: > Junio C Hamano <gitster@xxxxxxxxx> writes: >> Philip Oakley <philipoakley@iee.email> writes: >> >>> This may be not part of the the main project, but could you consider, if >>> time permits, also adding some entries into the Git Glossary (`git help >>> glossary`) for the various terms we are using here and elsewhere, e.g. >>> 'topological levels', 'generation number', 'corrected commit date' (and >>> its fancy technical name for the use of date heuristics e.g. the >>> 'chronological ordering';). >>> >>> The glossary can provide a reference, once the issues are resolved. The >>> History Simplification and Commit Ordering section of git-log maybe a >>> useful guide to some of the terms that would link to the glossary. >> Ah, I first thought that Documentation/rev-list-options.txt (which >> is the relevant part of "git log" documentation you mention here) >> already have references to deep technical terms explained in the >> glossary and you are suggesting Abhishek to mimic the arrangement by >> adding new and agreed-upon terms to the glossary and referring to >> them from the commit-graph documentation updated by this series. >> >> But sadly that is not the case. What you are saying is that you >> noticed that rev-list-options.txt needs a similar "the terms we use >> to explain these two sections should be defined and explained in the >> glossary (if they are not) and new references to glossary should be >> added there" update. >> >> In any case, that is a very good suggestion. I agree that updating >> "git log" doc may be outside the scope of Abhishek's theme, but it >> would be very good to have such an update by anybody ;-) > The only possible problem I see with this suggestion is that some of > those terms (like 'topological levels' and 'corrected commit date') are > technical terms that should be not of concern for Git user, only for > developers working on Git. (However one could encounter the term > "generation number" in `git commit-graph verify` output.) However we do mention "topolog*" in a number of the manual pages, and rather less, as yet, in the technical pages. "Lexicographic" and "chronological" are in the same group of fancy technical words ;-) > > I don't think adding technical terms that the user won't encounter in > the documentation or among messages that Git outputs would be not a good > idea. It could confuse users, rather than help them. > > Conversely, perhaps we should add Documentation/technical/glossary.txt > to help developers. I would agree that the Glossary probably ought to be split into the primary, secondary and background terms so that the core concepts are separated from the academic/developer style terms. Git does rip up most of what folks think about version "control", usually based on the imperfect replication of physical artefacts. > > P.S. By the way, when looking at Documentation/glossary-content.txt, I > have noticed few obsolescent entries, like "Git archive", few that have > description that soon could be or is obsolete and would need updating, > like "master" (when default branch switch to "main"), or "object > identifier" and "SHA-1" (when Git switches away from SHA-1 as hash > function). The obsolescent items can be updated. I'm expecting that the 'main' and 'SHA-' changes will eventually be picked up as part of the respective patch series, hopefully as part of the global replacements. -- Philip
