Re: Improving sed's manual

[Jim Meyering]

On Tue, Nov 29, 2016 at 3:11 PM, Jim Meyering <address@hidden> wrote:
> On Fri, Nov 25, 2016 at 12:56 PM, Jim Meyering <address@hidden> wrote:
>> On Fri, Nov 25, 2016 at 12:33 PM, Assaf Gordon <address@hidden> wrote:
>>> Hello,
>>>
>>> I've started working on improving sed's manual.
>>> It's far from complete, but feedback is welcomed.
>>>
>>> Generally, I'm aiming for the following:
>>> 1. Many more examples, embedded throughout the text.
>>> 2. examples are as self-contained as possible (e.g. including full command 
>>> line, and
>>> input and output where it's not obvious what the output should be)
>>> 3. expand regexp section, make ERE a standard section (not an appendix)
>>> 4. burrow several regexp sections from 'grep', and adjust for sed (e.g. 
>>> bracket expressions)
>>> 5. an "overview" at every new chapter, written with simple examples
>>>
>>> not-copmleted-yet:
>>> 6. reorder command lists differently (e.g. not "commands for SED gurus", 
>>> but more like "branching and flow control commands")
>>> 7. expand and document locale effects
>>> 8. expand on sed's advanced topics (e.g. buffers, cycles, etc.) but move it 
>>> to a later point in the manual.
>>>
>>>
>>> To save space, I'm not attaching the large patch.
>>> It is available here (messy commits, not finalized):
>>>   https://housegordon.org/sed-manual/sed-doc-2016-11-25.patch.xz
>>>
>>>
>>> Compare new-vs-current "table of content" (and the entire manual):
>>>   https://housegordon.org/sed-manual/sed-current.html#SEC_Contents
>>>   https://housegordon.org/sed-manual/sed-new.html
>>>
>>> Please disregard the CSS, it is a temporary style that just slightly nicer 
>>> than the default 'make info' output.
>>>
>>>
>>> Comments are very welcomed, both in phrasing/grammar/spelling and in 
>>> content/organization.
>>
>> Great!  Thank you for all of that.
>> I will make a point of looking through it in the next couple of days.
>>
>> By the way, as soon as gnulib's dfa module is ready for the upcoming
>> grep release, I would like to make a sed release, so if you have any
>> non-documentation pending changes that you would like to see included,
>> please let me know.
>
> I've applied and have begun to review.
> One nit: "make syntax-check" complains like this:
>
> doc/sed-in.texi:511:d @xref{
> doc/sed-in.texi:1850:e @xref{
> doc/sed.texi:512:d @xref{
> doc/sed.texi:1851:e @xref{
> maint.mk: undesirable word sequence
> maint.mk:998: recipe for target 'sc_prohibit_undesirable_word_seq' failed
> make: *** [sc_prohibit_undesirable_word_seq] Error 1
> make: *** Waiting for unfinished jobs....
>
> From memory, I usually chang those to @pxref or change their context,
> i.e., add/remove punctuation around them.
> If you can do that quickly and ensure that "make distcheck" still
> passes, you are welcome to push all of those changes. I will look
> through them in the next two hours. I'd like to make a snapshot today
> or tomorrow.

Here's a suggested change to fix those:
(note that I also had to commit a change to record the regenerated
sed.texi file)

sed-doc-syntax-check-vs-xref.diff
Description: Text document