Gnus-FAQ: xml to texi with Scheme prog

Gnus-FAQ: xml to texi with Scheme prog

[Karl Pflästerer]

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

Hi,
as some of you may know the Gnus FAQ exists at the moment in two
parallel versions which have to be synchronized manually: a XML version
(which should be the master version) and a Texi version (which should
get automagically created out of the XML version but is written by
hand).

To achieve the transformation I wrote a program in Scheme (I used PLT
Scheme) which uses the SSAX lib to parse the XML data.

I hope the program may be of use so it's easier for the different
versions of the FAQ to stay in sync.

I attach the program and a shell script which can get used to run the
program from the command line.


[-- Attachment #2: xml2texi.scm --]
[-- Type: application/octet-stream, Size: 16240 bytes --]

(require (lib "ssax.ss" "ssax")
         (lib "sxpath.ss" "ssax")
         (lib "sxml-tree-trans.ss" "ssax")
         (lib "pregexp.ss")
         (lib "list.ss")
         (lib "etc.ss")
         (rename (lib "1.ss" "srfi") list-index list-index)
         (rename (lib "13.ss" "srfi") string-join string-join))


;;; Constants
;; In and out; for convenience if we work from the REPL
(define +infile+ "gnus-faq.xml")
(define +outfile+ "gnus-faq.texi")

;; These are the names of the sections.  These variables hold the names
;; of the sections where numbering starts in the main menu.
;; Where we start numbering in menu
(define +first-numbered-section+ "Installation FAQ")
;; Where we end numbering in menu
(define +last-numbered-section+ "Tuning Gnus")

;; Which sections not to include; i.e. not to name a node.
(define +ignored-sections+ '("Frequently Asked Questions with Answers"))

;; Names of menu entries and the corresponding descriptions (used in the
;; main menu).
(define +section-comments-alist+
    '(("Introduction" . "About Gnus and this FAQ.")
      ("Installation FAQ" . "Installation of Gnus.")
      ("Startup / Group buffer" . "Start up questions and the first buffer Gnus shows you.")
      ("Getting Messages" . "Making Gnus read your mail and news.")
      ("Reading messages" . "How to efficiently read messages.")
      ("Composing messages" . "Composing mails or Usenet postings.")
      ("Old messages" . "Importing, archiving, searching and deleting messages.")
      ("Gnus in a dial-up environment" . "Reading mail and news while offline.")
      ("Getting help" . "When this FAQ isn't enough.")
      ("Tuning Gnus" .  "How to make Gnus faster.")
      ("Glossary" . "Terms used in the FAQ explained.")))

;; Where to break descriptions in menus
(define +width+ 72)

;; The boilerplate text we include before the document
(define boilerplate
    (lambda (titel)
      (format
       "\
@c \\input texinfo @c -*-texinfo-*-~%\
@c Uncomment 1st line before texing this file alone.~%\
@c %**start of header~%\
@c Copyright (C) 1995, 2001, 2003, 2004 Free Software Foundation, Inc.~%\
@setfilename gnus-faq.info~%\
@settitle ~A~%\
@c %**end of header~%\
" titel)))

;;; Little Helpers
;; (a b c) -> (1 2 3)
(define (number-list start inc lst)
    (let loop ((lst lst) (lvl start) (acc '()))
         (if (null? lst)
           (reverse acc)
           (loop (cdr lst) (+ inc lvl) (cons lvl acc)))))

;; Given an alist made of regexps and their replacements (key and value
;; are in a proper list) returns a function which given a string
;; replaces all occurences of the regexps (from left to right).
;; ((re1 repl1) (re2 repl2)) -> str -> str
(define make-reg-replacer
    (lambda (defalist)
      (let ((allreg (string-join (map car defalist) "|")))
        (lambda (str)
          (if (and (string? str) (pregexp-match allreg str))
            (let loop ((lst defalist) (str str))
                 (if (null? lst)
                   str
                   (loop (cdr lst) (pregexp-replace* (caar lst) str (cadar lst)))))
            str)))))

(define escape-texi
    (make-reg-replacer '(("@"  "@@") ("{"  "@{") ("}"  "@}"))))

(define normalize
    (compose escape-texi (make-reg-replacer `((,(format "~%\\s+") ,(format "~%"))))))

(define normalize-example
    (compose escape-texi (make-reg-replacer '(("^\\s+|\\s+$" "")))))

(define trim-ws (make-reg-replacer '(("^\\s+|\\s+$" ""))))

(define filter-sect
    (lambda (lst)
      (filter (lambda (e) (not (member e +ignored-sections+))) lst)))

;;;; Para
(define format-para
    (lambda (list-of-entries)
      (format "~%~A~%" (trim-ws (apply string-append list-of-entries)))))

;;;; Questions
(define format-q-level
    (lambda (level)
      (apply format "[~A.~A]" (reverse level))))

(define format-q-description
    (compose trim-ws (make-reg-replacer `((,(format "~%") " ")))))

;;;; Building nodes
;; curr-node up-node (list of nodes) (list of node names) ->
;;   ((curr-node curr-name) (next next-name) (prev prev-name) up)
(define (find-prev-next-up curr up search-list name-list)
    (do ((lst   search-list (cdr lst))
         (rlst  name-list   (cdr rlst))
         (prev  up   (car lst))
         (prevn up   (car rlst)))
        ((or (null? lst) (equal? (car lst) curr))
         (values (cons curr (if (pair? rlst) (car rlst) curr))
                 (if (and (pair? lst) (pair? (cdr lst))) ;next
                   (cons (cadr lst) (cadr rlst))
                   (cons "" ""))
                 (cons prev prevn)
                 up))))


(define (format-node section title up lst-of-nodes lst-of-names)
    (if (member title +ignored-sections+)
      ()
      (call-with-values
       (lambda () (find-prev-next-up title up lst-of-nodes lst-of-names))
       (lambda (currn prevn nextn up)
         (format "~%@node ~A, ~A, ~A, ~A~%~A ~A~%"
                 (cdr currn) (cdr prevn) (cdr nextn) up
                 section ;; @subsection etc.
                 (if (pair? title)
                   (apply format "~A.~A" (reverse title))
                   title))))))

;;;; Building menus

(define format-menu
    (lambda (alist-of-entries)
      (let ((len (apply max (map (lambda (s) (string-length (car s))) alist-of-entries))))
        (format "~%@menu~%~A@end menu~%"
                (apply string-append
                       (map (lambda (e)
                              (format "* ~A::~A~A~%"
                                      (car e) ;the entry
                                      (make-string (- len (string-length (car e)) -3) #\ )
                                      (format-menu-description (cdr e) +width+ (+ len 7))))
                            alist-of-entries))))))


(define format-menu-description
    (lambda (entry width offset)
      (let loop ((lst (pregexp-split "\\s" entry)) (len 0) (acc '()))
           (if (null? lst)
             (apply string-append (reverse! acc))
             (let ((slen (+ 1 (string-length (car lst))))) ; +1 because of whitespace added later
               (if (> (+ slen len) (- width offset))
                 (loop (cdr lst) 0 (cons
                                    (format "~%~A ~A"                 ; start a new line
                                            (make-string offset #\ ) ; the whitespace
                                            (car lst))
                                    acc))
                 (loop (cdr lst) (+ slen len) (cons (format " ~A"(car lst)) acc))))))))


(define format-sub-titles
    (lambda (list-of-entries first-number-entry last-number-entry)
      (let ((offset (or (list-index (lambda (e) (equal? e first-number-entry)) list-of-entries) 0))
            (end (or (list-index (lambda (e) (equal? e last-number-entry)) list-of-entries)
                     (length list-of-entries))))
      (map (lambda (entry ind)
             (format "FAQ ~A ~A"
                     (if (<= offset ind end)
                       (format "~A -" (- ind offset -1)) ;numbered entry
                       "-")
                     entry))
           list-of-entries (number-list 0 1 list-of-entries)))))

;;;; We number some sections first

;; ntags is an alist => ((tag startcounter increment)
(define (number-nodes tree level ntags)
    (if (null? ntags)
      tree
      (let* ((vals  (car ntags))
             (ntag  (car vals))
             (start (second vals))
             (inc   (third vals))
             (ntags (cdr ntags)))

        (map
         (lambda (node sublevel)
           (pre-post-order
            node
            `((,ntag *preorder*
                     . ,(lambda (tag . entry)
                          `(,tag ,(cons sublevel level)
                                 ,@(number-nodes entry (cons sublevel level) ntags))))
              (*default* . ,(lambda x x))
              (*text* . ,(lambda (tag s) s)))))
         tree (number-list start inc tree)))))


;;(transform->numbered faqsxml '(section article qandaset ((qandadiv 1 1) (qandaentry 0 1))))
(define transform->numbered
    (lambda (sxml rules)
      (let* ((rules (reverse rules))
             (rule (car rules))
             (ntag (cadr rules))
             (styles (map (lambda (tag) (cons tag (lambda x x))) (list-tail rules 2))))
  (pre-post-order
   sxml
     `((*default* *preorder* . ,(lambda x x))
       (*TOP* . ,(lambda x x))
       ,@styles
       (,ntag *preorder*
        . ,(lambda (tag . nodes)
             (cons tag (number-nodes nodes '() rule)))))))))


;;;; The main transform function

(define (transform sxml)
    (let* ((sxml (transform->numbered
                  sxml '(section article qandaset ((qandadiv 1 1) (qandaentry 0 1)))))
           (qandadivtitles (filter-sect (map second ((sxpath '(// qandadiv title)) sxml))))
           (fqandadivtitles (format-sub-titles qandadivtitles "" ""))
           (subtitles (filter-sect (append (map second ((sxpath '(// section title)) sxml))
                                           qandadivtitles
                                           (map second ((sxpath '(// glossary title)) sxml)))))
           (fsubtitles (format-sub-titles subtitles +first-numbered-section+
                                          +last-numbered-section+))
           (questlevel (map second ((sxpath '(article section qandaset qandadiv qandaentry)) sxml)))
           (up1 (cadar ((sxpath '(article articleinfo title)) sxml)))

;;; ************************************************************
;;; The Style Sheet
;;; ************************************************************
           (style-sheet
             `(
;;; ************************************************************
;;; First the SXML special markers
;;; ************************************************************
               ;; *TOP* *PI* @ are markers from SXML
               (*TOP* . ,(lambda (tag . x) x))
               (*PI* . ,(lambda _ '()))
               (@ . ,(lambda _ ""))

               ;; Look for the example rule where we overwrite the *text* rule
               ;; so code doesn't get mangled.
               (*text*
                . ,(lambda (tag string)
                     (normalize string)))
               ;; If nothing else matches
               (*default* . ,(lambda x x))
;;; ************************************************************
;;; Now to the tags of our FAQ
;;; ************************************************************
               (article . ,(lambda (tag . sects)
                             (cons (boilerplate up1) sects)))

               (articleinfo
                ((*default* . ,(lambda _ '()))
                 (title
                  . ,(lambda (tag titel)
                       (let ((menucom (map (lambda (entry)
                                             (let ((e (assoc entry +section-comments-alist+)))
                                               (if e (cdr e) "")))
                                           subtitles)))
                         (list (format-node '@section titel "" '() '())
                               (format-menu (map cons fsubtitles menucom)))))))
                . ,(lambda (tag . info) info))

               ;; Sections
               (abstract
                . ,(lambda (tag . text)
                     (cons (format "~%@subheading Abstract~%") text)))
               (section
                ((title
                  . ,(lambda (tag titel)
                       (format-node '@subheading titel up1 subtitles fsubtitles))))
                . ,(lambda (tag . entry) entry))

               ;; Q&A well it's called FAQ isn't it?
               (qandaset . ,(lambda (tag . x) x))
               (qandadiv
                ((title
                  . ,(lambda (tag titel) titel)))
                . ,(lambda (tag level titel . entries)
                     (let ((questions (map cadr entries))
                           (nlevel (filter (lambda (lvl) (eq? (car level) (cadr lvl))) questlevel)))
                       (list*
                        (format-node '@subsection titel up1 subtitles fsubtitles)
                        (format-menu (map (lambda (lvl quest)
                                            (cons (format-q-level lvl)
                                                  (format-q-description quest)))
                                          nlevel questions))
                        entries))))
               (qandaentry
                . ,(lambda (tag level question answer)
                     (let ((nodes
                             (filter (lambda (lvl) (eq? (cadr lvl) (cadr level))) questlevel))
                           (up (list-ref fqandadivtitles (- (cadr level) 1))))
                       (list*
                        (format-node "@subsubheading Question" level up nodes (map format-q-level nodes))
                        question answer))))
               (question . ,(lambda (tag quest) quest))
               (answer
                . ,(lambda (tag  . answ) (list* (format "~%@subsubheading Answer~%") answ)))

               ;; Para
               (para . ,(lambda (tag . x) (format-para x)))
               (simpara . ,(lambda (tag . x) (cons (format "~%")  x)))

               ;; Itemized lists.
               ;; We rewrite para here because it plays here the role of an
               ;; item marker
               (itemizedlist
                . ,(lambda (tag lstitem)
                     (format "~%@itemize @bullet~%~A@end itemize~%" lstitem)))
               (listitem
                ((para
                  . ,(lambda (tag item)
                       (format "~%@item~%~A~%" (trim-ws item)))))
                . ,(lambda (tag . x) (string-join x "")))

               ;; The glossary.
               (glossary
                ((title . ,(lambda _'())))
                . ,(lambda (tag . terms)
                     (let ((titel (cadar ((sxpath '(article glossary title)) sxml))))
                       (cons (format-node '@subsection titel up1 subtitles fsubtitles)
                             (list (format "~%@table @dfn~%")
                                   terms
                                   (format "~%@end table~%"))))))
               (glossentry . ,(lambda (tag . entry) entry))
               (glossterm
                . ,(lambda (tag term)
                     (format "~%@item ~A" term)))
               (glossdef
                . ,(lambda (tag def) def))

               ;; Lisp examples
               ;; We rewrite the *text* rule so code stays the way it's writen.
               (programlisting
                ((*text*
                  . ,(lambda (tag exampl)
                       (normalize-example exampl))))
                . ,(lambda (tag . exampl)
                     (format "~%@example~%~A~%@end example~%@noindent~%" (string-join exampl ""))))

               ;; The link handling
               ;; Here we are interested in the attributes, so we rewrite the @
               ;; rule.  If we find a value we look if it's an email or http
               ;; uri.
               (ulink
                ((@
                  . ,(lambda (at val) val)))
                . ,(lambda (tag uri name)
                     (if (pregexp-match "^http:|^ftp:" uri)
                       (format "@uref{~A, ~A}"  uri name)
                       (format "@email{~A, ~A}" (substring uri 7) name))))
               (url
                . ,(lambda (tag val) val))

               ;; userinput
               (userinput
                . ,(lambda (tag val)
                     (format "@samp{~A}" val)))
               )))
      (pre-post-order sxml style-sheet)))

;;;; We call main with infile and outfile as arguments
(define main
    (lambda (in out)
      (with-output-to-file out
        (lambda ()
          (call-with-input-file in
            (lambda (port)
              (SRV:send-reply (transform (ssax:xml->sxml port '()))))))
        'replace)))

[-- Attachment #3: xml2texi.sh --]
[-- Type: application/x-sh, Size: 1056 bytes --]

[-- Attachment #4: Type: text/plain, Size: 8 bytes --]



   KP

Re: Gnus-FAQ: xml to texi with Scheme prog

[Reiner Steib]

On Wed, Mar 09 2005, Karl Pflästerer wrote:

> as some of you may know the Gnus FAQ exists at the moment in two
> parallel versions which have to be synchronized manually: a XML version
> (which should be the master version) and a Texi version (which should
> get automagically created out of the XML version but is written by
> hand).
>
> To achieve the transformation I wrote a program in Scheme (I used PLT
> Scheme) which uses the SSAX lib to parse the XML data.

Thanks for your efforts, Karl.  It would be very nice to have only a
single source of the FAQ.

Could you elaborate which programs and/or libraries are required to
run this program?  I don't know anything about Scheme.

> #! /bin/sh
> #|
> exec mzscheme -mr $0 ${1+"$@"}
[...]

I can only find the following files related to "mzscheme" on my system
(SuSE 9.2):

/usr/lib/swig1.3/mzscheme$ file *
mzrun.swg:     ASCII C program text
mzscheme.swg:  ASCII C program text
precommon.swg: ASCII text
std_common.i:  ASCII C++ program text
[...]
std_vector.i:  ASCII C++ program text
typemaps.i:    ASCII C program text

> (require (lib "ssax.ss" "ssax")
>          (lib "sxpath.ss" "ssax")
>          (lib "sxml-tree-trans.ss" "ssax")

I didn't find any matches for those (using the package information
search).

Bye, Reiner.

PS: Could you please send me the resulting `gnus-faq.texi'?  Either on
    the list or by PM.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Gnus-FAQ: xml to texi with Scheme prog

[Karl Pflästerer]

On 15 Mrz 2005, reinersteib+gmane@imap.cc wrote:

> On Wed, Mar 09 2005, Karl Pflästerer wrote:
>
>> as some of you may know the Gnus FAQ exists at the moment in two
>> parallel versions which have to be synchronized manually: a XML version
>> (which should be the master version) and a Texi version (which should
>> get automagically created out of the XML version but is written by
>> hand).
>>
>> To achieve the transformation I wrote a program in Scheme (I used PLT
>> Scheme) which uses the SSAX lib to parse the XML data.

> Could you elaborate which programs and/or libraries are required to
> run this program?  I don't know anything about Scheme.

You simply need mzscheme; it's part of DrScheme but can also be
downloaded seperately (IIRC).
           http://www.plt-scheme.org/software/mzscheme/ 
describes that beter.


>> #! /bin/sh
>> #|
>> exec mzscheme -mr $0 ${1+"$@"}
> [...]
>
> I can only find the following files related to "mzscheme" on my system

I don't know if DrScheme or MzScheme comes exists as a Suse package but
there are Linux ports.


[...]
>> (require (lib "ssax.ss" "ssax")
>>          (lib "sxpath.ss" "ssax")
>>          (lib "sxml-tree-trans.ss" "ssax")
>
> I didn't find any matches for those (using the package information
> search).

These are part of the PLT Scheme distribution.


> PS: Could you please send me the resulting `gnus-faq.texi'?  Either on
>     the list or by PM.

I'll send it the next days.


   Karl

Re: Gnus-FAQ: xml to texi with Scheme prog

[Reiner Steib]

On Tue, Mar 15 2005, Karl Pflästerer wrote:
[ Scheme program to transform `gnus-faq.xml' to `gnus-faq.texi' ]

I have installed the files `xml2texi.scm' and `xml2texi.sh' in texi/
in the v5-10 branch.  I did some modifications on `xml2texi.scm' and
`gnus-faq.xml' to improve the printed output.

Some questions and remarks (not all related to xml2texi):

- `+section-comments-alist+' should be put into `gnus-faq.xml'.

-  The "Changes" section should not be present in the texi version.

-  Is there a possibility to add @cindex entries in `gnus-faq.xml'?

- <userinput>...</userinput> is translated to @samp{...}.  It would be
  nice to have @kbd{T n}, @code{tar xvzf ...}, @file{~/.gnus.el}, etc.

- Currently texi/gnus-faq.texi has the following arch tag:

,----
| @ignore
|    arch-tag: 64dc5692-edb4-4848-a965-7aa0181acbb8
| @end ignore
`----

How to deal with this?  Should we add something like...

  (insert "@ignore\n   "
          "arch-tag: "
	  "64dc5692-edb4-4848-a965-7aa0181acbb8"
          "\n@end ignore")

... in `main' in `xml2texi.scm'?  I guess this would make sure that it
is not confused with the arch tag of the file `xml2texi.scm'.  Miles?
(I will not install the re-created `gnus-faq.texi' before this is
clarified.)

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

Re: Gnus-FAQ: xml to texi with Scheme prog

[Miles Bader]

On Sun, 20 Mar 2005 20:55:25 +0100, Reiner Steib
<reinersteib+gmane@imap.cc> wrote:
> On Tue, Mar 15 2005, Karl Pflästerer wrote:
> [ Scheme program to transform `gnus-faq.xml' to `gnus-faq.texi' ]
> 
> I have installed the files `xml2texi.scm' and `xml2texi.sh' in texi/
> in the v5-10 branch.  I did some modifications on `xml2texi.scm' and
> `gnus-faq.xml' to improve the printed output.
...
> - Currently texi/gnus-faq.texi has the following arch tag:
> 
> ,----
> | @ignore
> |    arch-tag: 64dc5692-edb4-4848-a965-7aa0181acbb8
> | @end ignore
> `----
> 
> How to deal with this?

Should the generated file be in the archive at all?  Hmmm, I guess
scheme is an unusual enough language that you can't rely on developers
having it installed (is the implementation hairy enough that it can't
be done in elisp or awk or something?).

>  Should we add something like...
> 
>   (insert "@ignore\n   "
>           "arch-tag: "
>           "64dc5692-edb4-4848-a965-7aa0181acbb8"
>           "\n@end ignore")
> 
> ... in `main' in `xml2texi.scm'?  I guess this would make sure that it
> is not confused with the arch tag of the file `xml2texi.scm'.  Miles?

Yes that would probably work.  The rules for finding arch-tag: in a
file are roughly: (1)  somewhere in the first or last 1K (2K?) of the
file, and (2) string "arch-tag:" on a line preceded by nothing but
puncuation or whitespace.  So splitting the "arch-tag:" in the insert
would be a good idea (e.g., use "arch-" "tag:" instead of
"arch-tag:").

Another method is to use an arch `explicit' tag for the generated file
(gnus-faq.texi), instead of an embedded arch-tag: line; then the
scheme source wouldn't have to insert anything special.  The only
downsides to this are that (1) explicit tags are slightly more clumsy
than tag lines (file moves &c need explicit detection), and (2)
_changing_ the tag basically means it's a new file (so the entire
contents of the file will present in the changeset describing the
changeover, not a diff); of course this last point is only a one-time
cost.

> (I will not install the re-created `gnus-faq.texi' before this is
> clarified.)

Thanks for caring... :-/

-Miles
-- 
Do not taunt Happy Fun Ball.

Re: Gnus-FAQ: xml to texi with Scheme prog

[Reiner Steib]

On Sun, Mar 20 2005, Miles Bader wrote:

> On Sun, 20 Mar 2005 20:55:25 +0100, Reiner Steib
> <reinersteib+gmane@imap.cc> wrote:
> Should the generated file be in the archive at all?  Hmmm, I guess
> scheme is an unusual enough language that you can't rely on developers
> having it installed

Yes, this is the main reason.  And not only developers but also users
need `gnus-faq.texi' to generate the manual.

> (is the implementation hairy enough that it can't be done in elisp
> or awk or something?).

The main problem is the DocBook/XML parsing, I'd guess.  Maybe Karl
can comment on this.

> So splitting the "arch-tag:" in the insert would be a good idea
> (e.g., use "arch-" "tag:" instead of "arch-tag:").

Karl (or anyone else familiar with Scheme), how can we add something
like...

  (insert "@ignore\n   arch-" "tag: "
	  "64dc5692-edb4-4848-a965-7aa0181acbb8"
          "\n@end ignore")

... to `main' in `xml2texi.scm'?

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

Re: Gnus-FAQ: xml to texi with Scheme prog

[Karl Pflästerer]

On 20 Mrz 2005, reinersteib+gmane@imap.cc wrote:

>
> On Tue, Mar 15 2005, Karl Pflästerer wrote:
> [ Scheme program to transform `gnus-faq.xml' to `gnus-faq.texi' ]
>
> I have installed the files `xml2texi.scm' and `xml2texi.sh' in texi/
> in the v5-10 branch.  I did some modifications on `xml2texi.scm' and
> `gnus-faq.xml' to improve the printed output.
>
> Some questions and remarks (not all related to xml2texi):
>
> - `+section-comments-alist+' should be put into `gnus-faq.xml'.

As I wrote in pm I think the best place for that information would be
attributes to the section titles.  If that would be changed I could
change also the Scheme program. 

> -  The "Changes" section should not be present in the texi version.

I'll look for that.


> -  Is there a possibility to add @cindex entries in `gnus-faq.xml'?

XML knows some sort of index commands; so if they were present in the
XML source they could be included in the generated texi file.  Maybe
this could be done together with the solution for the
+section-comments-alist+'.

> - <userinput>...</userinput> is translated to @samp{...}.  It would be
>   nice to have @kbd{T n}, @code{tar xvzf ...}, @file{~/.gnus.el}, etc.

I used the same format I found in the texi file.  The problem I see
here: how should the translating program know when to use e.g. @kbd and
when @code since both forms are included with the same tag: `userinput'

Maybe we find together a solution.

> - Currently texi/gnus-faq.texi has the following arch tag:
>
> ,----
>| @ignore
>|    arch-tag: 64dc5692-edb4-4848-a965-7aa0181acbb8
>| @end ignore
> `----
>
> How to deal with this?  Should we add something like...
>
>   (insert "@ignore\n   "
>           "arch-tag: "
> 	  "64dc5692-edb4-4848-a965-7aa0181acbb8"
>           "\n@end ignore")
>
> ... in `main' in `xml2texi.scm'?  I guess this would make sure that it
> is not confused with the arch tag of the file `xml2texi.scm'.  Miles?
> (I will not install the re-created `gnus-faq.texi' before this is
> clarified.)
>
> Bye, Reiner.

   KP

Re: Gnus-FAQ: xml to texi with Scheme prog

[Karl Pflästerer]

On 20 Mrz 2005, snogglethorpe@gmail.com wrote:

> Should the generated file be in the archive at all?  Hmmm, I guess
> scheme is an unusual enough language that you can't rely on developers
> having it installed (is the implementation hairy enough that it can't
> be done in elisp or awk or something?).

Well it was easiest with Scheme; it could be done with any language
where you have libs (or write yourself some) with which you can parse
and transform the XML source.  Scheme with SSAX libs works very good
here (and shouldn't be sooo unusual in a community of (X)Emacs users).

>
>>  Should we add something like...
>> 
>>   (insert "@ignore\n   "
>>           "arch-tag: "
>>           "64dc5692-edb4-4848-a965-7aa0181acbb8"
>>           "\n@end ignore")
>> 
>> ... in `main' in `xml2texi.scm'?  I guess this would make sure that it
>> is not confused with the arch tag of the file `xml2texi.scm'.  Miles?
>
> Yes that would probably work.  The rules for finding arch-tag: in a
> file are roughly: (1)  somewhere in the first or last 1K (2K?) of the
> file, and (2) string "arch-tag:" on a line preceded by nothing but
> puncuation or whitespace.  So splitting the "arch-tag:" in the insert
> would be a good idea (e.g., use "arch-" "tag:" instead of
> "arch-tag:").

A solution for this should be trivial.


   KP

Re: Gnus-FAQ: xml to texi with Scheme prog

[Karl Pflästerer]

On 21 Mrz 2005, reinersteib+gmane@imap.cc wrote:


>   (insert "@ignore\n   arch-" "tag: "
> 	  "64dc5692-edb4-4848-a965-7aa0181acbb8"
>           "\n@end ignore")
>
> ... to `main' in `xml2texi.scm'?

You could simply rewrite the rule for the article.

At the moment it is:

               (article . ,(lambda (tag . sects)
                             (cons (boilerplate up1) sects)))

it could be:

               (article . ,(lambda (tag . sects)
                             (list (boilerplate up1) sects
                                    (format "\
~%@c @bye~%\
@ignore~%\
arch-\
tag: 64dc5692-edb4-4848-a965-7aa0181acbb8~%\
@end ignore~%"))))

Clearly what is written as format ... should be defined as variable and
simply included there.

Like e.g.

(define +this-is-the-end-my-friend+
    (format "\
@c @bye~%\
@ignore~%\
arch-\
tag: 64dc5692-edb4-4848-a965-7aa0181acbb8~%\
@end ignore"))

               (article . ,(lambda (tag . sects)
                             (list (boilerplate up1) sects 
                                   +this-is-the-end-my-friend+)))


Or something similar.


   KP

Re: Gnus-FAQ: xml to texi with Scheme prog

[Miles Bader]

Reiner Steib <reinersteib+gmane@imap.cc> writes:
>> (is the implementation hairy enough that it can't be done in elisp
>> or awk or something?).
>
> The main problem is the DocBook/XML parsing, I'd guess.  Maybe Karl
> can comment on this.

Hmmm, I'd say the advisability of using DocBook/XML in the first place
is open to question (DocBook seems to be one of those horrid `who cares
if the insanely verbose markup completely obscures the contents' markup
languages).

-Miles
-- 
We have met the enemy, and he is us.  -- Pogo

Re: Gnus-FAQ: xml to texi with Scheme prog

[Reiner Steib]

On Mon, Mar 21 2005, Miles Bader wrote:

> Hmmm, I'd say the advisability of using DocBook/XML in the first place
> is open to question (DocBook seems to be one of those horrid `who cares
> if the insanely verbose markup completely obscures the contents' markup
> languages).

I don't know why Frank Schmitt (author of the FAQ for Gnus > 5.8) has
chosen DocBook/XML.

Miles, could you install xml2texi.* (plus ChangeLog entries) in the
trunk or shall I do it?  I though that this would happen (semi-)
automatically because all changes from v5-10 are supposed to go in the
trunk, too.

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

Re: Gnus-FAQ: xml to texi with Scheme prog

[Reiner Steib]

On Sun, Mar 20 2005, Reiner Steib wrote:

> - `+section-comments-alist+' should be put into `gnus-faq.xml'.
>
> -  The "Changes" section should not be present in the texi version.

At least the CVS $ID$ should not be included.  I'm not sure if the
faq-discuss mailing list is necessary.

> -  Is there a possibility to add @cindex entries in `gnus-faq.xml'?
>
> - <userinput>...</userinput> is translated to @samp{...}.  It would be
>   nice to have @kbd{T n}, @code{tar xvzf ...}, @file{~/.gnus.el}, etc.

Other items that might need update:

,----[ (info "(gnus)[3.11]") ]
| Can I tell Gnus not to delete the mails on the server it  retrieves via
| POP3?
`----

We have a poor man's (no "UID_" support) `pop3-leave-mail-on-server'
now, see its doc-string.

,----[ (info "(gnus)[2.4]") ]
| My group buffer becomes a bit crowded, is there a way to  sort my
| groups into categories so I can easier browse  through them?
`----

Should mention how to do this permanently.

,----[ (info "(gnus)[3.7]") ]
| And how about local spool files?
`----

I don't think this is "frequently asked", is it?

,----[ (info "(gnus)[3.9]") ]
| And what about IMAP?
`----

Why do we include `nnimap-port' and `nnimap-list-pattern' there.  I
think it would be less confusing and less error prone to omit the
server variables because most users won't need them.

Anyhow.  I will check in the generated file soon.

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

Re: Gnus-FAQ: xml to texi with Scheme prog

[Miles Bader]

Reiner Steib <reinersteib+gmane@imap.cc> writes:
> Miles, could you install xml2texi.* (plus ChangeLog entries) in the
> trunk or shall I do it?  I though that this would happen (semi-)
> automatically because all changes from v5-10 are supposed to go in the
> trunk, too.

Yes, I've done so; I was holding off a bit until things settled down.

-Miles
-- 
Ich bin ein Virus. Mach' mit und kopiere mich in Deine .signature.

Re: Gnus-FAQ: xml to texi with Scheme prog

[Miles Bader]

BTW, is this stuff safe to put in Emacs (WRT assignments, etc)?

Thanks,

-Miles
-- 
Do not taunt Happy Fun Ball.

Re: Gnus-FAQ: xml to texi with Scheme prog

[Reiner Steib]

On Wed, Mar 23 2005, Miles Bader wrote:

> BTW, is this stuff safe to put in Emacs (WRT assignments, etc)?

Karl Pflästerer (who wrote the xml2texi.* files) and Frank Schmitt
(who wrote the FAQ) both told me that they have assignments on file.
I don't have access to the list; maybe you can double check it?

As for xml2texi.*, I'm not sure if we need to include it in Emacs.

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

Re: Gnus-FAQ: xml to texi with Scheme prog

[Miles Bader]

On Wed, 23 Mar 2005 09:56:36 +0100, Reiner Steib
<reinersteib+gmane@imap.cc> wrote:
> As for xml2texi.*, I'm not sure if we need to include it in Emacs.

Maybe it should be brought up on the Emacs list, I don't know...

Even if nobody ever runs them, it seems nice to have the program used
for generating the FAQ available.

BTW, maybe the the generator program should put a comment saying
something like "do not modify this file, it was generated from ..." at
the top of the generated file.

-Miles
-- 
Do not taunt Happy Fun Ball.

Re: Gnus-FAQ: xml to texi with Scheme prog

[Reiner Steib]

On Wed, Mar 23 2005, Miles Bader wrote:

> BTW, maybe the the generator program should put a comment saying
> something like "do not modify this file, it was generated from ..." at
> the top of the generated file.

Done.

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