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 17:07:53 -0800

On Tue, Nov 29, 2016 at 3:16 PM, Jim Meyering <address@hidden> wrote:
> 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)

This looks great. THanks for all of that work.
I'm happy to include that in the upcoming release.
I haven't read through all of it, but did find a few typos:

s/commnad/command/

-Older verion accepted it but treated it as a single bracket expression
+Older versions accepted it but treated it as a single bracket expression

These were highlighted when I ran the "misspellings" program from
https://github.com/lyda/misspell-check:

doc/sed-in.texi:121: occurances -> "occurrences"
doc/sed-in.texi:156: supressing -> "suppressing"
doc/sed-in.texi:157: supressing -> "suppressing"
doc/sed-in.texi:534: occured -> "occurred"
doc/sed-in.texi:1045: acheive -> "achieve"
doc/sed-in.texi:2790: surronded -> "surrounded"
doc/sed-in.texi:2914: dependant -> "dependent"

Sending this now (even though not done), because I'll be interrupted shortly.



reply via email to

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