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.) 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. 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). Best, -- Jakub Narębski
