Follow-up Comment #3, bug#65098 (group groff): [comment #2 comment #2:] > Dealing with gropdf.pl separately, I have cobbled together a document > which may help you in the task. It is a list of all the diffs with a > following comment which describes what the changes accomplish. One way > of handling this is to introduce each file as a separate commit and > include a description of what the changes in each file achieve (from > the embedded comments). Note that I have removed from the diff changes > to master since deri-gropdf-ng was branched.
Yes! That sounds much more tractable. Thank you--I'll have a look. > Gropdf.pl is a slightly different kettle of fish, it has grown by over > 25% (over 1000 lines), and the number of new lines of code is more > than that because there has been significant code deletion as well. Yes. > You may remember there was a code freeze for over 6 months before > 1.23.0 and after 3 months I got an "itch" and wrote the new version, > you then suggested I start a new branch, so I slammed the new version > into that. I have already written about the two main drivers for the > change: making gropdf subset fonts in the pdf, and switching from a > word based input model to an input stream of glyph names (you said > that my description was helpful). Indeed. > So just as adding a new program to a project does not lead to a raft > of commits detailing every new function in the code, but rather the > commit would describe what new features the new program adds to the > project, it would probably be best to treat the new gropdf in a > similar way - describing what has been added to groff's capabilities. True, but _gropdf_ _is_ an existing program, so for maintainability I think that ideally, we'd handle it the same way as the changes described in the first paragraph above. This would also be consistent with other major changes to groff features we see in the commit and changelog histories, particularly in the Werner Lemberg era of maintenance. That said, I don't want to _gate_ the merge of your changes on such a documentary record. Perfect being the enemy of the good and all that. > I'm afraid I did not get your red tree reference, my only experience > with red/black trees is in "binary chop" and there is a self balancing > algorithm for that. Right, sorry about that. I refer to a convention in continuous integration (and some other development) systems such that builds are automated after every commit, and if a build fails on any of the N supported configurations, the "tree (of source code) goes red", that is, becomes unacceptable for deployment to production. Normally, the tree is "green", and ready to ship any time a manager/release engineer/"Agile scrum master" elects to do so. > Maintainability is more concerned with understanding the code as it > is, the git log may help you understand how it got there but > understanding what the code actually achieves can only be understood > by reading the code. For example if I want to know what > ps_output::put_string does then git log tells me that isascii got > changed to is_ascii in 1994, but it tells me nothing about what the > routine does. Maintainability of code is far more about the quality of > code and the knowledge and experience of the person looking at the > code. I think I got lost here with respect to which of these distinct aspects is more important to maintainability, but I agree that they're both virtues. > I've had a rethink about an.tmac and stripped out all the stuff added > to MR, since it was only there to support internal links to other > pages within a man page book (such as groff_man_pages.pdf), and I have > found an alternative way of achieving the same thing without touching > an.tmac. All that is left is stuff to make it work with the new > gropdf, don't use \E* do use \\*, and add support for UR/UE and MT/ME. Oh, that's interesting. The "special pleading" for `MR` was one of the things that felt not-quite-baked to me. > I know you are working on/planning your for iterator, but please don't > hold up merging my branch to wait for it, since in its current state > it all works without it. Agreed. It is hard for me to predict when any particular thunderbolt will appear in my bucket ready for hurling. I thought resolution of bug #62471 was months in the future for a long time (a year or more?), and then all of a sudden the fog lifted and, prompted by [https://gitlab.com/man-db/man-db/-/merge_requests/11 a discussion] with Colin Watson and наб in a man-db merge request, I was able to land a fix with little effort by attacking the problem from a different angle. > When your code is complete we can revisit which parts are helpful for > gropdf. Agreed, and this can likely serve as a form of regression test to boot. > Just out of interest: what does ch contain if N is set (i.e. it is a > node). Stage 1: I was thinking it would return nothing, an empty string. You'd just pump the iterator again to get the next thing. But that's pretty weak sauce because we need a way to signal that iteration has stopped. Python raises a StopIteration exception, for example. But the *roff language has neither exceptions or even return values, strictly considered. So, _initially_, your iterator "character" would contain nothing if you had hit a node or the end of the iterand. That will not actually be unworkable because: 1. If you use the `for` or `rfor` requests, they will only exit (barring a `break`) once iteration has stopped. 2. I don't at this point imagine a more primitive means of driving an iterator, but if that should happen, one can always use the `length` request beforehand to measure the iterand, and make sure not to pump the iterator more than $length times. But that seems to me only a little less fiddly than the existing things we have to do when iterating strings. So... Stage 2: Add a new conditional operator, "N". .ie N ch .tm it's a node .el .tm it's not a node That seems like it should be easy/simple to do. So if `ch` interpolates nothing and is not a node, iteration has stopped. Stage 3: Add a new `pnode` request to dump information about a node to the standard error output. Not useful for *roff _programming_ (that is, it's not really "in the language" per se), but potentially very valuable for *roff _development_ (including applications). My instincts tell me I'd want all 3 of these together, so these stages would not necessarily be distantly separated. If they prove to be easy, they might be a sequence of adjacent commits in a single push. Feedback very much desired. Regards, Branden _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?65098> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
