Better integration of the new Gnus FAQ in Oort

Better integration of the new Gnus FAQ in Oort

[Reiner Steib]

Hi,

up to now, we have the Gnus FAQ as an article in the group
`nndoc+gnus-help:gnus-help'.  It's planned to convert the FAQ from
docbook to info format, but this hasn't been done, because of
technical problems (Frank Schmitt may provide details).

Wouldn't it be nice, if we could refer to the FAQ in a convenient
manner when answering postings in Gnus newsgroups?  There should be
buttons to be able to refer directly to some FAQ entry or to start a
text search within the FAQ, e.g.:

  (gnus-faq-search "mm-text-html-renderer")
  (gnus-faq-goto-heading "render my HTML-mails")
  (gnus-faq-goto-item "4.7") ; maybe?

Similar to the buttons that we have for info already:

  (Info-goto-node "(gnus)Group Information")
  <info://gnus/Group+Information>

It would make much sense, if we could get this to work before the
release of Gnus 5.10.

An advantage of the above mentioned `gnus-faq-*' functions would be,
that we can still use the buttons and functions when the FAQ has been
converted to info successfully: Instead of jumping to the nndoc
article, the functions will go to the info node.

What do people think?  I could add the buttons easily.  Can someone
give me hints on how to implement the "jump to
`nndoc+gnus-help:gnus-help' and go to ..." part in a reasonably
manner?  Or better send code. ;-)

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

Re: Better integration of the new Gnus FAQ in Oort

[Ted Zlatanov]

On Fri, 11 Apr 2003, 4.uce.03.r.s@nurfuerspam.de wrote:
> An advantage of the above mentioned `gnus-faq-*' functions would be,
> that we can still use the buttons and functions when the FAQ has
> been converted to info successfully: Instead of jumping to the nndoc
> article, the functions will go to the info node.
> 
> What do people think?  I could add the buttons easily.  Can someone
> give me hints on how to implement the "jump to
> `nndoc+gnus-help:gnus-help' and go to ..." part in a reasonably
> manner?  Or better send code. ;-)

I like the idea, and I can write the code to get the article but I
don't know how to do the parsing necessary to jump to a section or
item number.

I think we should also buttonize every instance of "gnus faq item
[0-9.]+" (case-insensitive).  That way, you can just say "see gnus FAQ
item 4.7" and a link would be shown to the user.  Asking users to run
Lisp code may be a problem for novices.

Ted

Re: Better integration of the new Gnus FAQ in Oort

[Reiner Steib]

On Fri, Apr 11 2003, Ted Zlatanov wrote:

> On Fri, 11 Apr 2003, 4.uce.03.r.s@nurfuerspam.de wrote:
>> What do people think?  I could add the buttons easily.  Can someone
>> give me hints on how to implement the "jump to
>> `nndoc+gnus-help:gnus-help' and go to ..." part in a reasonably
>> manner?  Or better send code. ;-)
>
> I like the idea, and I can write the code to get the article but I
> don't know how to do the parsing necessary to jump to a section or
> item number.

This was my problem too, but I though it was just my ignorance.  :-)
IMHO, ideally, we should have something like incremental search or `i'
and `,' in info.  Is this feasible?  Ideas?

Please post the code, even if the jump-to thingie is missing.
Probably somebody on the list will know how to fill the gap.

> I think we should also buttonize every instance of "gnus faq item
> [0-9.]+" (case-insensitive).  

Yes, this can be added easily.  The button regexps are
case-insensitive anyhow.

> That way, you can just say "see gnus FAQ item 4.7" and a link would
> be shown to the user.  

This would be similar to "in article <mid>" buttons:

    ("\\bin\\( +article\\| +message\\)? +\\(<\\([^\n @<>]+@[^\n @<>]+\\)>\\)"
     2 (>= gnus-button-message-level 0) gnus-button-message-id 3)

> Asking users to run Lisp code may be a problem for novices.

If we have buttons for such stuff in 5.10, novice users just have to
press RET or mouse-2 on stuff like (gnus-faq-search
"mm-text-html-renderer").  (And it's international.)  We often see
answers like "See `C-h v some-var RET'." even now---that non-Oort
users don't have buttons for.  And my impression is, that those
answers are appreciated by novices.

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

Re: Better integration of the new Gnus FAQ in Oort

[Jesper Harder]

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

> It's planned to convert the FAQ from docbook to info format, but this
> hasn't been done, because of technical problems (Frank Schmitt may
> provide details).

What's the problem?  I just converted it to Texinfo, and it seems work
fine.  

There are few formating details that might be worth to adjust in the XML
source with Texinfo output in mind, but nothing major.

Re: Better integration of the new Gnus FAQ in Oort

[Kai Großjohann]

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

> This was my problem too, but I though it was just my ignorance.  :-)
> IMHO, ideally, we should have something like incremental search or `i'
> and `,' in info.  Is this feasible?  Ideas?

Maybe the easiest way to get `i' support is to convert it to Texinfo.
:-)
-- 
file-error; Data: (Opening input file no such file or directory ~/.signature)

Re: Better integration of the new Gnus FAQ in Oort

[Reiner Steib]

On Sat, Apr 12 2003, Jesper Harder wrote:

> Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:
>
>> It's planned to convert the FAQ from docbook to info format, but this
>> hasn't been done, because of technical problems (Frank Schmitt may
>> provide details).
>
> What's the problem?  I just converted it to Texinfo, and it seems work
> fine.  

I don't know (and I don't have the necessary docbook tools on my
machine).  Frank?

> There are few formating details that might be worth to adjust in the
> XML source with Texinfo output in mind, but nothing major.

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

Re: Better integration of the new Gnus FAQ in Oort

[Frank Schmitt]

Jesper Harder <harder@myrealbox.com> writes:

> Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:
>
>> It's planned to convert the FAQ from docbook to info format, but this
>> hasn't been done, because of technical problems (Frank Schmitt may
>> provide details).
>
> What's the problem?  I just converted it to Texinfo, and it seems work
> fine.  

Way cool, how did you do it? The problem was that the only way to
convert docbook to texinfo known to us was docbook2X and all attampts
to use it failed because either docbook2X didn't build (over here at
Windows - Cygwin country) or it only partially converted the FAQ and
gave up somewhere in the middle.

If you could send me a receipt on how you did it, this would be of
great help.

-- 
"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: Better integration of the new Gnus FAQ in Oort

[Jesper Harder]

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

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

> Way cool, how did you do it? The problem was that the only way to
> convert docbook to texinfo known to us was docbook2X and all attampts
> to use it failed because either docbook2X didn't build (over here at
> Windows - Cygwin country) or it only partially converted the FAQ and
> gave up somewhere in the middle.

I used docbook2x as well.

> If you could send me a receipt on how you did it, this would be of
> great help.

* I removed the "<?xml" stuff, 

* pointed to a docbook DTD on my system, and

* Changed the title.  It seems to use the title as file name, and it
  breaks if there are spaces in it.  I don't know docbook, but there's
  probably some way to specify the file name in the markup.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: gnus-faq.xml.diff --]
[-- Type: text/x-patch, Size: 1011 bytes --]

--- orig.gnus-faq.xml	Sat Apr 12 22:31:42 2003
+++ gnus-faq.xml	Sat Apr 12 22:34:31 2003
@@ -1,12 +1,10 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<?xml-stylesheet type="text/css" href="css/docbook-xml.css"?>
-
-<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN' 'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>
+<!--DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN' 'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'-->
 <!--DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN' 'file:///usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd'-->
+<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN' 'file:////usr/share/apps/ksgmltools2/docbook/xml-dtd-4.1.2/docbookx.dtd'>
 
 <article>
   <articleinfo>
-    <title>Frequently Asked Questions</title>
+    <title>Frequently_Asked_Questions</title>
     <!-- @setfilename gnus-faq.info -->
     <!-- FIXME: Somebody should clean up the copyright stuff in a legally correct fashion -->
     <copyright>

Re: Better integration of the new Gnus FAQ in Oort

[Lars Magne Ingebrigtsen]

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

> Wouldn't it be nice, if we could refer to the FAQ in a convenient
> manner when answering postings in Gnus newsgroups? 

That would be nice, but wouldn't it make more sense to just use URLs
and refer to a web page?

>   (gnus-faq-search "mm-text-html-renderer")
>   (gnus-faq-goto-heading "render my HTML-mails")
>   (gnus-faq-goto-item "4.7") ; maybe?

On the other hand, that wouldn't be possible with a web page.  :-)

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

Re: Better integration of the new Gnus FAQ in Oort

[Frank Schmitt]

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

> I hope that Frank will succeed in producing a nice texinfo version.
> Then we can use `C-h i d m gnus-faq RET i mm-text-html-renderer RET'
> and `C-h i d m gnus-faq RET s render my HTML-mails RET' and add
> buttons for it.

Hmm, in fact it isn't me who works on the texinfo version, I'm only a
stupid Windows user with little knowledge about this stuff. :-)

-- 
"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: Better integration of the new Gnus FAQ in Oort

[Ted Zlatanov]

On Sat, 12 Apr 2003, 4.uce.03.r.s@nurfuerspam.de wrote:
> On Fri, Apr 11 2003, Ted Zlatanov wrote:

>> I like the idea, and I can write the code to get the article but I
>> don't know how to do the parsing necessary to jump to a section or
>> item number.
> 
> Please post the code, even if the jump-to thingie is missing.
> Probably somebody on the list will know how to fill the gap.

Are we jumping to an article number or to a message subject?

Ted

Re: Better integration of the new Gnus FAQ in Oort

[Reiner Steib]

On Mon, Apr 14 2003, Ted Zlatanov wrote:

> Are we jumping to an article number or to a message subject?

I guess it doesn't matter too much.  Since the article number in the
doc group (10) isn't changing, you could use it.

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

Re: Better integration of the new Gnus FAQ in Oort

[Ted Zlatanov]

On Mon, 14 Apr 2003, 4.uce.03.r.s@nurfuerspam.de wrote:
> On Mon, Apr 14 2003, Ted Zlatanov wrote:
> 
>> Are we jumping to an article number or to a message subject?
> 
> I guess it doesn't matter too much.  Since the article number in the
> doc group (10) isn't changing, you could use it.

This should do it then:

(with-temp-buffer
  (gnus-request-article-this-buffer 10 "nndoc+gnus-help:gnus-help"))

Then in the temp-buffer form you can do whatever you want with the FAQ
body.

Hmm, I wonder if there's a gnus-request-article-peek?
gnus-request-article-this-buffer and friends seem to affect the
article marks, which we don't want in this case.

Ted

Re: Better integration of the new Gnus FAQ in Oort

[Lars Magne Ingebrigtsen]

Ted Zlatanov <tzz@lifelogs.com> writes:

> (with-temp-buffer
>   (gnus-request-article-this-buffer 10 "nndoc+gnus-help:gnus-help"))

There is a function for just reading a single article from a group
without creating a summary buffer and all that jazz.  But I can't for
the life of me remember what it's called, and I've spent five minutes
trying to find it.

Perhaps I didn't write the function, but only thought about it?

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

Re: Better integration of the new Gnus FAQ in Oort

[Ted Zlatanov]

On Tue, 15 Apr 2003, larsi@gnus.org wrote:
> Ted Zlatanov <tzz@lifelogs.com> writes:
> 
>> (with-temp-buffer
>>   (gnus-request-article-this-buffer 10
>>   "nndoc+gnus-help:gnus-help"))
> 
> There is a function for just reading a single article from a group
> without creating a summary buffer and all that jazz.  But I can't
> for the life of me remember what it's called, and I've spent five
> minutes trying to find it.
> 
> Perhaps I didn't write the function, but only thought about it?

You know, this is how programmers know it's time for a vacation :)

If you or someone else finds this function or writes it, let me know
since I can use it in spam.el and nnimap-db.el (under construction).

Thanks
Ted