[Patch] FAQ in texinfo format

[Patch] FAQ in texinfo format

[Frank Schmitt]

[-- Attachment #1: Type: text/plain, Size: 377 bytes --]

Hello

I've now finished (with the friendly help of Jesper Harder and the
docbook2x maintainer) the texinfo version of the Gnus FAQ. I attach it
together with an update to the FAQ in the nndoc group (do we need this
any longer when texinfo is ready?).

Please give comments and if everything is alright, could anybody with
CVS write access please commit the stuff?

MFG Frank


[-- Attachment #2: Updates to the FAQ, texinfo version. --]
[-- Type: application/octet-stream, Size: 37448 bytes --]

[-- Attachment #3: Type: text/plain, Size: 252 bytes --]



-- 
"You know the world is going crazy when the best rapper is a white guy,
the best golfer is a black guy, the Swiss hold the America's Cup, France
is accusing the US of arrogance, and Germany doesn't want to go to war."
          -- Unknown author

Re: [Patch] FAQ in texinfo format

[Kai Großjohann]

Frank Schmitt <usereplyto@Frank-Schmitt.net> writes:

> I've now finished (with the friendly help of Jesper Harder and the
> docbook2x maintainer) the texinfo version of the Gnus FAQ. I attach it
> together with an update to the FAQ in the nndoc group (do we need this
> any longer when texinfo is ready?).
>
> Please give comments and if everything is alright, could anybody with
> CVS write access please commit the stuff?

It looks quite nice.

However, I'm thinking maybe it would be even better to have the source
available.  Unless, that is, you want to switch, so that people
consider the Texinfo version the source code from now on.

What do people think?
-- 
file-error; Data: (Opening input file no such file or directory ~/.signature)

Re: [Patch] FAQ in texinfo format

[Karl Pflästerer]

On 20 Apr 2003, Kai Großjohann <- kai.grossjohann@gmx.net wrote:

> It looks quite nice.

> However, I'm thinking maybe it would be even better to have the source
> available.  Unless, that is, you want to switch, so that people
> consider the Texinfo version the source code from now on.

> What do people think?

Well I can only speak for me but if I wanted to add something to the faq
it would be a lot easier if it was in texi than in xml (insert your most
favourite rant here). So IMO it would be better to switch the master
version to texi.

bye
   KP

-- 
"Lisp is worth learning for the profound enlightenment experience you
will have when you finally get it; that experience will make you a
better programmer for the rest of your days, even if you never
actually use Lisp itself a lot."                    -- Eric S. Raymond

Re: [Patch] FAQ in texinfo format

[Frank Schmitt]

[This is a repost since the first message seems to have gone lost on
it's way through the news<->mail gateway on news.gnus.org]

sigurd@12move.de (Karl Pflästerer) writes:

> On 20 Apr 2003, Kai Großjohann <- kai.grossjohann@gmx.net wrote:
>
>> It looks quite nice.
>
>> However, I'm thinking maybe it would be even better to have the source
>> available.  Unless, that is, you want to switch, so that people
>> consider the Texinfo version the source code from now on.
>
>> What do people think?

Well, the xml-source is no big help as I hand-edited the output of docbook2x
to quite a large degree. Further on, I see the FAQ as independent from
Gnus itself, so my idea was to update the texinfo version included in
Gnus before a new Gnus release (and sometimes between two releases to
keep the required work down) and let the actual process of improving and
updating the FAQ happen through the FAQ discussion list.

> Well I can only speak for me but if I wanted to add something to the faq
> it would be a lot easier if it was in texi than in xml (insert your most
> favourite rant here). So IMO it would be better to switch the master
> version to texi.

If anybody wants to contribute to the FAQ, it's as easy as to send the
question-answer pair (or fragments, ideas etc) to the FAQ discussion
list or me directly, I prefer to do the rest myself to keep a
homogeneous style.

MFG Frank

-- 
"You know the world is going crazy when the best rapper is a white guy,
the best golfer is a black guy, the Swiss hold the America's Cup, France
is accusing the US of arrogance, and Germany doesn't want to go to war."
          -- Unknown author

Re: [Patch] FAQ in texinfo format

[Steinar Bang]

>>>>> Frank Schmitt <usereplyto@Frank-Schmitt.net>:

> Well, the xml-source is no big help as I hand-edited the output of
> docbook2x to quite a large degree.

Just out of curiosity: why was the hand editing neccessary?  What kind
of stuff did you have to change?

Re: [Patch] FAQ in texinfo format

[Frank Schmitt]

Steinar Bang <sb@dod.no> writes:

>>>>>> Frank Schmitt <usereplyto@Frank-Schmitt.net>:
>
>> Well, the xml-source is no big help as I hand-edited the output of
>> docbook2x to quite a large degree.
>
> Just out of curiosity: why was the hand editing neccessary?  What kind
> of stuff did you have to change?

The output of docbook2x didn't have the questions numbered, so I added
this, further on all the questions had been one node with the section
names as just bold text. I changed it so that every section is  a
section and that every question - answer pair is a node (and a
subsection) to make it easier to jump to a specific question.

I also deleted some stuff which is only useful for the website and the
text version (which I hope to post regularly to gnu.emacs.gnus soon),
e.g. the changes section.

-- 
"You know the world is going crazy when the best rapper is a white guy,
the best golfer is a black guy, the Swiss hold the America's Cup, France
is accusing the US of arrogance, and Germany doesn't want to go to war."
          -- Unknown author

Re: [Patch] FAQ in texinfo format

[Reiner Steib]

On Mon, Apr 21 2003, Frank Schmitt wrote:

Frank, I have committed the new `gnus-faq.texi'.  Your patch for
`make.bat' shouldn't be necessary.  `gnus-faq.texi' is @include-d by
`gnus.texi'.  I had to do quite a lot of changes to allow the
inclusion again.  (Maybe there's a more simple solution than my hacks,
but I'm too tired now.)

> The output of docbook2x didn't have the questions numbered, so I added
> this, further on all the questions had been one node 

Making each question a node is a good idea.

> with the section names as just bold text. 

A number in a numbered section isn't nice in the printed versions.  So
I used @subheading commands.

> I also deleted some stuff which is only useful for the website and
> the text version (which I hope to post regularly to gnu.emacs.gnus
> soon), e.g. the changes section.

This might be solved with @ifinfo or @ifset (@ifclear).

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

Re: [Patch] FAQ in texinfo format

[Frank Schmitt]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:

> Frank, I have committed the new `gnus-faq.texi'.  Your patch for
> `make.bat' shouldn't be necessary.  `gnus-faq.texi' is @include-d by
> `gnus.texi'.  I had to do quite a lot of changes to allow the
> inclusion again.  (Maybe there's a more simple solution than my hacks,
> but I'm too tired now.)

Is putting it under Appendix really a good idea? It's quite hidden
there. What was wrong with having it as a seperate info file?

-- 
"You know the world is going crazy when the best rapper is a white guy,
the best golfer is a black guy, France is accusing the US of arrogance,
and Germany doesn't want to go to war." -- Unknown author

Re: [Patch] FAQ in texinfo format

[Kai Großjohann]

Frank Schmitt <usereplyto@Frank-Schmitt.net> writes:

> Is putting it under Appendix really a good idea? It's quite hidden
> there. What was wrong with having it as a seperate info file?

Let's put it in a more prominent place, but in the general Gnus info
file.  There are so many info files for Gnus, people don't read them
anyway :-(  Gnus, Message, Emacs-MIME come to mind at least.

-- 
file-error; Data: (Opening input file no such file or directory ~/.signature)

Re: [Patch] FAQ in texinfo format

[Reiner Steib]

On Tue, Apr 22 2003, Kai Großjohann wrote:

> Frank Schmitt <usereplyto@Frank-Schmitt.net> writes:
>
>> Is putting it under Appendix really a good idea? It's quite hidden
>> there. 

ACK.  The old version of the FAQ has been there, so I though that the
new version should be placed there too.

>> What was wrong with having it as a seperate info file?
> Let's put it in a more prominent place, 

ACK.

> but in the general Gnus info file.  

I'm not sure.

> There are so many info files for Gnus, people don't read them anyway
> :-( Gnus, Message, Emacs-MIME come to mind at least.

... and Sieve and PGG.  But as we have menu items for those in (info
"(gnus)Top") under "Other related manuals", it should be more easy to
find them.  

I guess we cannot include the manuals for message etc. into gnus.texi,
because those are libraries, that are supposed to be independent of
Gnus.  This argument doesn't hold for the Gnus FAQ.

Instead of putting the FAQ as a @section in the "@chapter Appendices",
it could be a @chapter, included e.g. before "@chapter Appendices".
When included in `gnus.texi', we must take care not to have duplicate
node names (this is why I prepended "FAQ").

If we choose the `separate info file' approach, we need to add links
to the FAQ under "Other related manuals".  And, as @menu is invisible
in dvi/ps/pdf output, we should add some hints in the printed versions
too (also for Message, Emacs-MIME, Sieve, PGG).  We can revert
gnus-faq.texi to Frank's version (revision 6.9) then, but we need to
fix gnus.texi[1].

Aside from the Gnus FAQ, there may be other documents to be
distributed along with Gnus, so we should come to some kind of general
guidelines, how to include (or refer to) those documents:

- Translations of docs to non-English languages, e.g. Xavier
  Maillard's French docs.

- The Gnus Tutorial: It's development seems to be stalled.  But
  anyhow, I think after some minor fixes, we should add it to the Gnus
  distribution.  Contributions and corrections welcome! [2]

[ Cc: faq-discuss@my.gnus.org, gnus-tutorial@socha.net ]

Bye, Reiner.

[1]
./gnus-faq.texi:11: Node `Top' previously defined at line 380.
./gnus-faq.texi:12: Node with @top as a section already exists.
./gnus.texi:380: Here is the @top node.
./gnus.texi:26513: Next reference to nonexistent node 
  `Frequently Asked Questions' (perhaps incorrect sectioning?).
./gnus.texi:380: Node `Top' lacks menu item for 
  `Introduction' despite being its Up target.
./gnus.texi:380: Node `Top' lacks menu item for 
  `Frequently Asked Questions with Answers' despite being its Up target.
./gnus.texi:380: Node `Top' lacks menu item for 
  `Glossary' despite being its Up target.
./gnus.texi:23097: Menu reference to nonexistent node 
  `Frequently Asked Questions' (perhaps incorrect sectioning?).
./gnus.texi:872: Cross reference to nonexistent node 
  `Frequently Asked Questions' (perhaps incorrect sectioning?).
makeinfo: Removing output file `gnus' due to errors; use --force to preserve.

[2]
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gnus login
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gnus co gnus-tutorial
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo--- PGP key available via WWW   http://rsteib.home.pages.de/

Re: [Patch] FAQ in texinfo format

[Steinar Bang]

>>>>> sigurd@12move.de (Karl Pflästerer):

> Well I can only speak for me but if I wanted to add something to the
> faq it would be a lot easier if it was in texi than in xml (insert
> your most favourite rant here). So IMO it would be better to switch
> the master version to texi.

I think it would be wrong to dictate a volunteer's choice of tools.

Also, there's a lot more "happening" with DocBook XML, than with
TeXinfo.  DocBook XML is a great master source to generate other
formats from.  Not because it's XML.  That's coincidental.  But
because it aims towards semantic markup, rather than visual markup.

But I agree the DocBook XML source for the FAQ should be in CVS,
perferrably with synchronized checkins of the generated TeXinfo file
(never check in one and not the other).

Re: [Patch] FAQ in texinfo format

[Karl Pflästerer]

On 20 Apr 2003, Steinar Bang <- sb@dod.no wrote:

>>>>>> sigurd@12move.de (Karl Pflästerer):

>> Well I can only speak for me but if I wanted to add something to the
>> faq it would be a lot easier if it was in texi than in xml (insert
>> your most favourite rant here). So IMO it would be better to switch
>> the master version to texi.

> I think it would be wrong to dictate a volunteer's choice of tools.

Me too, but I didn't dictate anything.  I only wrote my opinion
concerning Kais sugestion *if* the maintainer would like to switch the
format what others think about it.

> Also, there's a lot more "happening" with DocBook XML, than with
> TeXinfo.  DocBook XML is a great master source to generate other
> formats from.  Not because it's XML.  That's coincidental.  But

Please don't let us start a xml pro con flame here. I don't like xml
because I think it has gone the wrong way (especially lispers should
know better how to write markup usings sexps) (I think Erik naggum wrote
on cll some time ago an excellent article concerning xml, but I don't
have the m-id).

But you are right. it is the maintainers choice. He does the work he can
choose how it is most convenient for him.

> But I agree the DocBook XML source for the FAQ should be in CVS,
> perferrably with synchronized checkins of the generated TeXinfo file
> (never check in one and not the other).

If the xml file should also in future be the source I agree with you.

bye
   KP

-- 
Increasingly, people seem to misinterpret complexity as
sophistication, which is baffling -- the incomprehensible should cause
suspicion rather than admiration. Possibly this trend results from a
mistaken belief that using a somewhat mysterious device confers an
aura of power on the user.                                  -- Niklaus Wirth

One more patch (was: [Patch] FAQ in texinfo format)

[Frank Schmitt]

[-- Attachment #1: Type: text/plain, Size: 602 bytes --]

Frank Schmitt <usereplyto@Frank-Schmitt.net> writes:

> I've now finished (with the friendly help of Jesper Harder and the
> docbook2x maintainer) the texinfo version of the Gnus FAQ. I attach it
> together with an update to the FAQ in the nndoc group (do we need this
> any longer when texinfo is ready?).
>
> Please give comments and if everything is alright, could anybody with
> CVS write access please commit the stuff?

Here's a patch against make.bat to build gnus-faq.texi, I must admit
that I've no idea what to change in texi/Makefile.in to do the same but
perhaps someone else can do this.


[-- Attachment #2: Build gnus-faq.texi --]
[-- Type: application/octet-stream, Size: 1169 bytes --]

--- make.bat	2003-04-19 22:14:54.000000000 +0200
+++ make.bat.new	2003-04-20 19:02:54.000000000 +0200
@@ -132,6 +132,8 @@
 if ErrorLevel 1 set ERROR=%ERROR%,pgg.texi
 %EMACSINFO% message.texi
 if ErrorLevel 1 set ERROR=%ERROR%,message.texi
+%EMACSINFO% gnus-faq.texi
+if ErrorLevel 1 set ERROR=%ERROR%,gnus-faq.texi
 
 if not "%2" == "/copy" goto nocopy
 if not exist %GNUS_INFO_DIR% mkdir %GNUS_INFO_DIR%
@@ -155,6 +157,8 @@
 if ErrorLevel 1 set ERROR=%ERROR%,copy-sieve-info
 xcopy /R /Q /Y pgg        %GNUS_INFO_DIR%
 if ErrorLevel 1 set ERROR=%ERROR%,copy-pgg-info
+xcopy /R /Q /Y gnus-faq   %GNUS_INFO_DIR%
+if ErrorLevel 1 set ERROR=%ERROR%,copy-gnus-faq-info
 
 echo.
 echo ***************************************************************************
@@ -163,7 +167,8 @@
 echo * if they aren't already there:
 echo *
 echo * * PGG: (pgg).	Emacs interface to various PGP implementations.
-echo * * Sieve: (sieve).	Managing Sieve scripts in Emacs.
+echo * * Sieve: (sieve).      Managing Sieve scripts in Emacs.
+echo * * Frequently Asked Questions:   The new FAQ for Gnus.
 echo ***************************************************************************
 echo.
 

[-- Attachment #3: Type: text/plain, Size: 74 bytes --]


and I forgot that the info files shall be named foo instead of foo.info


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #4: Setfilename gnus-faq instead of gnus-faq.info --]
[-- Type: text/x-patch, Size: 311 bytes --]

--- texi/gnus-faq.texi	2003-04-19 22:32:08.000000000 +0200
+++ texi/gnus-faq.texi.new	2003-04-20 19:04:24.000000000 +0200
@@ -1,6 +1,6 @@
 \input texinfo                  @c -*-texinfo-*-\input texinfo
 
-@setfilename gnus-faq.info
+@setfilename gnus-faq
 @settitle The Gnus FAQ.
 @dircategory Emacs
 @direntry

[-- Attachment #5: Type: text/plain, Size: 355 bytes --]


However, I must admit that I like the foo.info variant much better,
what's the reason to just use foo?

-- 
"You know the world is going crazy when the best rapper is a white guy,
the best golfer is a black guy, the Swiss hold the America's Cup, France
is accusing the US of arrogance, and Germany doesn't want to go to war."
          -- Unknown author

Re: One more patch

[Lars Magne Ingebrigtsen]

Frank Schmitt <usereplyto@Frank-Schmitt.net> writes:

> Here's a patch against make.bat to build gnus-faq.texi, I must admit
> that I've no idea what to change in texi/Makefile.in to do the same but
> perhaps someone else can do this.
>
> and I forgot that the info files shall be named foo instead of foo.info

Neither patch would apply cleanly -- have they already been applied,
or something?

> However, I must admit that I like the foo.info variant much better,
> what's the reason to just use foo?

Uhm...  I think somebody just decided on using suffixless info files
at some point.

-- 
(domestic pets only, the antidote for overdose, milk.)
   larsi@gnus.org * Lars Magne Ingebrigtsen

Re: One more patch

[Frank Schmitt]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> Frank Schmitt <usereplyto@Frank-Schmitt.net> writes:
>
>> Here's a patch against make.bat to build gnus-faq.texi, I must admit
>> that I've no idea what to change in texi/Makefile.in to do the same but
>> perhaps someone else can do this.
>>
>> and I forgot that the info files shall be named foo instead of foo.info
>
> Neither patch would apply cleanly -- have they already been applied,
> or something?

Yes, Reiner Steib applied them (with minor changes).

-- 
WANTED: A nice signature
REWARD: none

Re: One more patch

[Reiner Steib]

On Sun, Apr 27 2003, Lars Magne Ingebrigtsen wrote:

> Frank Schmitt <usereplyto@Frank-Schmitt.net> writes:
>
>> Here's a patch against make.bat to build gnus-faq.texi, I must admit
>> that I've no idea what to change in texi/Makefile.in to do the same but
>> perhaps someone else can do this.
[...]
> Neither patch would apply cleanly -- 

I've changed `make.bat' to binary (see ChangeLog) because of the line
terminator problem.

> have they already been applied, or something?

No.  As I wrote in <news:v9smsb7ajy.fsf@marauder.physik.uni-ulm.de>,
this patch isn't necessary, as `gnus-faq.texi' is included by
`gnus.texi'.  Unless we decide to start distributing the Gnus FAQ as a
separate info file, see the discussion in
<news:v9r87ur5fn.fsf@marauder.physik.uni-ulm.de> and parent articles.

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

Re: One more patch

[Lars Magne Ingebrigtsen]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:

> No.  As I wrote in <news:v9smsb7ajy.fsf@marauder.physik.uni-ulm.de>,
> this patch isn't necessary, as `gnus-faq.texi' is included by
> `gnus.texi'.

Oh, sorry; I didn't read that thread all carefully enough.

-- 
(domestic pets only, the antidote for overdose, milk.)
   larsi@gnus.org * Lars Magne Ingebrigtsen