Splitting gnus.texi (was: Split man directory)

Splitting gnus.texi (was: Split man directory)

[Reiner Steib]

On Wed, Sep 05 2007, Juri Linkov wrote:

> Some manuals are very large (e.g. calc.texi, gnus.texi).  It makes sense
> to create a separate directory under doc/ for packages with large manuals
> and split these manuals to smaller files.

It might make sense to make a separate directory for Gnus manual files
(in current Gnus trunk: gnus-coding, gnus-news, gnus-faq, gnus) or
Gnus-related files (the former plus message, sasl, emacs-mime, pgg and
sieve).  But what would be the benefit of splitting gnus.texi into
several files?

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Splitting gnus.texi (was: Split man directory)

[Richard Stallman]

It would be good to split gnus.texi into 10 to 15 files
just because it is so big.  Similar for calc.texi.

Re: Splitting gnus.texi

[Katsumi Yamaoka]

>>>>> Richard Stallman wrote:

> It would be good to split gnus.texi into 10 to 15 files
> just because it is so big.  Similar for calc.texi.

At least for gnus.texi, I don't see the benefit of splitting.
It's indeed big, but is not too big to edit with Emacs.  Rather,
I cannot ignore a disadvantage of splitting it.  I sometimes
write in it.  Since various Gnus functions are related mutually,
I frequently check other items concerned when I write something.
For example, when I write description about nntp, I have to check
whether my writing does not conflict with descriptions of other
sections.  When I hesitate whether I should add @vindex for the
nntp-foo-bar variable, I scan the whole gnus.texi.  I do also it
when I examine it should be @acronym{NNTP}, @code{nntp}, or NNTP.
Now I only need to type `C-s nntp' for them.  But if gnus.texi is
split into 10 to 15 files, it will be quite troublesome.

I can agree with splitting if it is very useful to users, though.

Regards,

Re: Splitting gnus.texi

[Reiner Steib]

On Wed, Sep 26 2007, Katsumi Yamaoka wrote:

>>>>>> Richard Stallman wrote:
>
>> It would be good to split gnus.texi into 10 to 15 files
>> just because it is so big.  Similar for calc.texi.
>
> At least for gnus.texi, I don't see the benefit of splitting.
> It's indeed big, but is not too big to edit with Emacs.  Rather,
> I cannot ignore a disadvantage of splitting it.  I sometimes
> write in it.  Since various Gnus functions are related mutually,
> I frequently check other items concerned when I write something.
> [...]  But if gnus.texi is split into 10 to 15 files, it will be
> quite troublesome.
>
> I can agree with splitting if it is very useful to users, though.

Additionally, splitting destroys CVS annovate (vc-annotoate).  I also
see no problem with the size.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Splitting gnus.texi

[Giorgos Keramidas]

On 2007-09-26 08:07, Reiner Steib <reinersteib+gmane@imap.cc> wrote:
>On Wed, Sep 26 2007, Katsumi Yamaoka wrote:
>>>>>>> Richard Stallman wrote:
>>
>>> It would be good to split gnus.texi into 10 to 15 files
>>> just because it is so big.  Similar for calc.texi.
>>
>> At least for gnus.texi, I don't see the benefit of splitting.
>> It's indeed big, but is not too big to edit with Emacs.  Rather,
>> I cannot ignore a disadvantage of splitting it.  I sometimes
>> write in it.  Since various Gnus functions are related mutually,
>> I frequently check other items concerned when I write something.
>> [...]  But if gnus.texi is split into 10 to 15 files, it will be
>> quite troublesome.
>>
>> I can agree with splitting if it is very useful to users, though.
>
> Additionally, splitting destroys CVS annovate (vc-annotoate).  I also
> see no problem with the size.

This doesn't have to be the result of splitting.  The files may be
'repo-copied' by one of the CVS admins, creating let's say 3 files:

     gnus.texi
     gnus-news.texi
     gnus-email.texi

These files can then be 'trimmed' with a normal commit, and the trimmed
text becomes a changeset of its own.  This way 'cvs annotate' will still
show useful information.

Re: Splitting gnus.texi

[Reiner Steib]

On Sun, Sep 30 2007, Giorgos Keramidas wrote:

> On 2007-09-26 08:07, Reiner Steib <reinersteib+gmane@imap.cc> wrote:
>> Additionally, splitting destroys CVS annovate (vc-annotoate).  I also
>> see no problem with the size.
>
> This doesn't have to be the result of splitting.  The files may be
> 'repo-copied' by one of the CVS admins, creating let's say 3 files:
>
>      gnus.texi
>      gnus-news.texi
>      gnus-email.texi
>
> These files can then be 'trimmed' with a normal commit, and the trimmed
> text becomes a changeset of its own.  This way 'cvs annotate' will still
> show useful information.

... but e.g. "cvs ... co -r v5-10 gnus" will create bogus gnus-*.texi
files.  This is a no-no.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Splitting gnus.texi

[Giorgos Keramidas]

On 2007-09-30 23:34, Reiner Steib <reinersteib+gmane@imap.cc> wrote:
>On Sun, Sep 30 2007, Giorgos Keramidas wrote:
>> On 2007-09-26 08:07, Reiner Steib <reinersteib+gmane@imap.cc> wrote:
>>> Additionally, splitting destroys CVS annovate (vc-annotoate).  I also
>>> see no problem with the size.
>>
>> This doesn't have to be the result of splitting.  The files may be
>> 'repo-copied' by one of the CVS admins, creating let's say 3 files:
>>
>>      gnus.texi
>>      gnus-news.texi
>>      gnus-email.texi
>>
>> These files can then be 'trimmed' with a normal commit, and the trimmed
>> text becomes a changeset of its own.  This way 'cvs annotate' will still
>> show useful information.
>
> ... but e.g. "cvs ... co -r v5-10 gnus" will create bogus gnus-*.texi
> files.  This is a no-no.

Indeed, or someone has to go through the 'copies' and delete the tags
which are no longer relevant.  I understand that this is just an "ugly
hack", so let's avoid it if there isn't a very good reason to split
`gnus.texi' :-)

Re: Splitting gnus.texi

[Juri Linkov]

> At least for gnus.texi, I don't see the benefit of splitting.
> It's indeed big, but is not too big to edit with Emacs.  Rather,
> I cannot ignore a disadvantage of splitting it.  I sometimes
> write in it.  Since various Gnus functions are related mutually,
> I frequently check other items concerned when I write something.
> For example, when I write description about nntp, I have to check
> whether my writing does not conflict with descriptions of other
> sections.  When I hesitate whether I should add @vindex for the
> nntp-foo-bar variable, I scan the whole gnus.texi.  I do also it
> when I examine it should be @acronym{NNTP}, @code{nntp}, or NNTP.
> Now I only need to type `C-s nntp' for them.  But if gnus.texi is
> split into 10 to 15 files, it will be quite troublesome.

We can improve C-s to search a collection of files, but this is
not implemented yet.

> I can agree with splitting if it is very useful to users, though.

This is intended for developers.  So if developers think this is
not useful then there is no need to split it.

I proposed splitting only because source files for the Emacs manual are
split into several texi files.  However, I see no clear benefits
of splitting.  Rather we could take the suggestion of Reiner and put
gnus-coding, gnus-news, gnus-faq, gnus, message, sasl, emacs-mime,
pgg and sieve into a new `gnus' subdirectory.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Directory doc/gnus in Emacs CVS (was: Splitting gnus.texi)

[Reiner Steib]

On Wed, Sep 26 2007, Juri Linkov wrote:

>> I can agree with splitting if it is very useful to users, though.
>
> This is intended for developers.  So if developers think this is
> not useful then there is no need to split it.
>
> I proposed splitting only because source files for the Emacs manual are
> split into several texi files.  However, I see no clear benefits
> of splitting.  

Me neither.

> Rather we could take the suggestion of Reiner and put gnus-coding,
> gnus-news, gnus-faq, gnus, message, sasl, emacs-mime, pgg and sieve
> into a new `gnus' subdirectory.

For the record some explanations about these files:

  - gnus*.el are (parts of) core Gnus manuals. 
  
  - Message:(message).         Composing messages.
  - Emacs-MIME:(emacs-mime).   Composing messages; MIME-specific parts.
  
  Both are supposed to be independent from Gnus.  Alas it they are not
  anymore.  emacs-mime is also used by MH-E.  AFAICS, the MH-E manual
  describes the relevant MH-E specific stuff  and has some references to
  the emacs-mime and Gnus manual.
  
  - Sieve:(sieve).             Managing Sieve scripts in Emacs.
  - PGG:(pgg).                 PGP/MIME with Gnus.
  - SASL:(sasl).               SASL authentication in Emacs.
  
  These are independent from Gnus.

It would be fine with me to include those in a separate doc/gnus
directory.  But maybe the authors Simon Josefsson (sieve) and Daiki
Ueno (pgg and sasl) would prefer to have them in doc/misc.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Directory doc/gnus in Emacs CVS

[Bill Wohler]

Reiner Steib <reinersteib+gmane@imap.cc> writes:

> For the record some explanations about these files:
>
>   - gnus*.el are (parts of) core Gnus manuals. 
>   
>   - Message:(message).         Composing messages.
>   - Emacs-MIME:(emacs-mime).   Composing messages; MIME-specific parts.
>   
>   Both are supposed to be independent from Gnus.  Alas it they are not
>   anymore.  emacs-mime is also used by MH-E.  AFAICS, the MH-E manual
>   describes the relevant MH-E specific stuff  and has some references to
>   the emacs-mime and Gnus manual.

Yes, we (MH-E) have some cross-references as you describe. What is the
effect on our cross-references of putting these manuals in a gnus
sub-directory? Would the cross-references still work in both Emacs
22.2 and pre-Emacs 22.2 environments?

Sorry for the long delay, but work and summer activities have kept me away.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD

Re: Directory doc/gnus in Emacs CVS

[Reiner Steib]

On Sun, Oct 21 2007, Bill Wohler wrote:

> Reiner Steib <reinersteib+gmane@imap.cc> writes:
>
>> For the record some explanations about these files:
>>
>>   - gnus*.el are (parts of) core Gnus manuals. 
>>   
>>   - Message:(message).         Composing messages.
>>   - Emacs-MIME:(emacs-mime).   Composing messages; MIME-specific parts.
>>   
>>   Both are supposed to be independent from Gnus.  Alas it they are not
>>   anymore.  emacs-mime is also used by MH-E.  AFAICS, the MH-E manual
>>   describes the relevant MH-E specific stuff  and has some references to
>>   the emacs-mime and Gnus manual.
>
> Yes, we (MH-E) have some cross-references as you describe. What is the
> effect on our cross-references of putting these manuals in a gnus
> sub-directory? Would the cross-references still work in both Emacs
> 22.2 and pre-Emacs 22.2 environments?

There's no effect because the resulting info files would still be
installed in the standard directory.  It's just about re-organizing
the *.texi files.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Directory doc/gnus in Emacs CVS

[Richard Stallman]

Is it possible to make Emacs-MIME work with M-x mail?