sed-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Improving sed's manual


From: Jim Meyering
Subject: Re: Improving sed's manual
Date: Tue, 29 Nov 2016 15:11:13 -0800

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.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]