On 26.10.20 15:53, David G. Johnston wrote:
Removing -docs as moderation won’t let me cross-post.
On Monday, October 26, 2020, David G. Johnston <david.g.johnston@gmail.com> wrote:
On Monday, October 26, 2020, Jürgen Purtz <juergen@purtz.de> wrote:
On 21.10.20 22:33, David G. Johnston wrote:
Two, I find the amount of detail being provided here to be on the too-much side. A bit more judicious use of links into the appropriate detail chapters seems warranted.
The patch is intended to give every interested person an overall impression of the chapter within its new position. Because it has moved from part 'Tutorial' to 'Internals' the text should be very accurate concerning technical issues - like all the other chapters in this part. A tutorial chapter has a more superficial nature.
Haven’t reviewed the patches yet but...
I still think that my comment applies even with the move to internals. The value here is putting together a coherent narrative and making deeper implementation details accessible. If those details are already covered elsewhere in the documentation (not source code) links should be given serious consideration.
David J.
Please find the new patch in the attachment after integrating David's suggestions: a) versus the last patch and b) versus master.
Notably it contains
- nearly all of his suggestions (see sgml file for comments 'DGJ')
- reduction of <firstterm>. This was a hangover from the pre-glossary-times. I tried to emphasis standard terms. This is no longer necessary because nowadays they are clearly defined in the glossary.
--
J. Purtz