fetchmail-devel

[fetchmail-devel] FAQ re-write

[Rob M. <rob...@gm...>]

Recent events have persuaded me to get my proverbial finger out and
look at re-writing the FAQ to be more "user friendly" (and a little
more current).

With this in mind I'm soliciting feedback before I start :)

I'm considering splitting it into a number of pages, rather than the
monolithic page it is currently.  My current plan is that these would
cover (including the current areas):

1) (G) General, with an initial paragraph emphasising the need to use
the current version BEFORE asking for help with any problems

2) (B and F) Build problems and configuration file problems

3) (S and I) Problems downloading email

4) (T, D and M)) Problems passing email to your local mail system

5) (K) Proxies and Security (including SSL and SOCKS)

6) (R and H) Runtime problems

7) (C and M) Configuration problems and examples

8) (X and O) Everything else

Actually, I'd really like to get this into a Wiki because it means
that it's easier to work on it as I get time, plus it means that
others can easily add to/correct it as required.  I don't know if
Berlios has such functionality though (but I do know that pbwiki.com
is free).

Thoughts?

-- 
Rob MacGregor
      Whoever fights monsters should see to it that in the process he
        doesn't become a monster.                  Friedrich Nietzsche

Re: [fetchmail-devel] FAQ re-write

[Matthias A. <mat...@gm...>]

Rob MacGregor schrieb:
> Recent events have persuaded me to get my proverbial finger out and
> look at re-writing the FAQ to be more "user friendly" (and a little
> more current).
> 
> With this in mind I'm soliciting feedback before I start :)
> 
> I'm considering splitting it into a number of pages, rather than the
> monolithic page it is currently.  My current plan is that these would
> cover (including the current areas):
> 
> 1) (G) General, with an initial paragraph emphasising the need to use
> the current version BEFORE asking for help with any problems
> 
> 2) (B and F) Build problems and configuration file problems
> 
> 3) (S and I) Problems downloading email
> 
> 4) (T, D and M)) Problems passing email to your local mail system
> 
> 5) (K) Proxies and Security (including SSL and SOCKS)
> 
> 6) (R and H) Runtime problems
> 
> 7) (C and M) Configuration problems and examples
> 
> 8) (X and O) Everything else
> 
> Actually, I'd really like to get this into a Wiki because it means
> that it's easier to work on it as I get time, plus it means that
> others can easily add to/correct it as required.  I don't know if
> Berlios has such functionality though (but I do know that pbwiki.com
> is free).
> 
> Thoughts?

Your help will be very welcome.

a. the split is a good idea, although I'm not sure about the "everything
else" part and if I'd split 3) and 4) - these are often intertwined, and
we'd have to make sure 6) doesn't contain parts that belong into 3 or 4.

b. Berlios have a Wiki, but I'm a bit concerned about the packaging process
- I can't seem to find an export static pages version, but haven't got the
time now to check the site documentation for BerliOS.

Generally speaking, any Wiki we use must be able to export the whole set of
pages as static documents with working links and with marginal to zero
effort - I want to ship the FAQ with the fetchmail package; pointing users
to online sites for documentation is not something I'm eager to do - sooner
or later someone will be trying to read that info while Berlios has some
sort of downtime... oops. Can pbwiki.com export HTML and PDF?

In the hope of further discussion on the "how"

Best regards
Matthias

Re: [fetchmail-devel] FAQ re-write

[Rob M. <rob...@gm...>]

On 8/22/07, Matthias Andree <mat...@gm...> wrote:
>
> Your help will be very welcome.
>
> a. the split is a good idea, although I'm not sure about the "everything
> else" part and if I'd split 3) and 4) - these are often intertwined, and
> we'd have to make sure 6) doesn't contain parts that belong into 3 or 4.

As long as it's pointers I think that's ok.  I'm trying to think of
how people approach the "it's broken" thought process.

As for "everything else", I ran out of thoughts then :)

> b. Berlios have a Wiki, but I'm a bit concerned about the packaging process
> - I can't seem to find an export static pages version, but haven't got the
> time now to check the site documentation for BerliOS.

If it's accessible to the general public I'll have a look later
tonight (I should have an hour or so of time to myself :>).

> Generally speaking, any Wiki we use must be able to export the whole set of
> pages as static documents with working links and with marginal to zero
> effort - I want to ship the FAQ with the fetchmail package; pointing users
> to online sites for documentation is not something I'm eager to do - sooner
> or later someone will be trying to read that info while Berlios has some
> sort of downtime... oops. Can pbwiki.com export HTML and PDF?

I've no idea, but I'll have a look.  I do agree that making
assumptions about the future presence of a web site isn't good.

> In the hope of further discussion on the "how"

And, once the dust settles on this, I'd like to discuss the "how" of
re-working the small novel that is the man page.  That too I feel
needs a split and re-write - every other man page has the command line
options fairly close to the start, not a few dozen screens in.

-- 
                 Please keep list traffic on the list.

Rob MacGregor
      Whoever fights monsters should see to it that in the process he
        doesn't become a monster.                  Friedrich Nietzsche

Re: [fetchmail-devel] FAQ re-write

[Matthias A. <mat...@gm...>]

Rob MacGregor schrieb:

>> b. Berlios have a Wiki, but I'm a bit concerned about the packaging process
>> - I can't seem to find an export static pages version, but haven't got the
>> time now to check the site documentation for BerliOS.
> 
> If it's accessible to the general public I'll have a look later
> tonight (I should have an hour or so of time to myself :>).

It is accessible, check <http://developer.berlios.de/wiki/?group_id=1824> -
not much there yet except some internal development stuff that is outdated...

>> In the hope of further discussion on the "how"
> 
> And, once the dust settles on this, I'd like to discuss the "how" of
> re-working the small novel that is the man page.  That too I feel
> needs a split and re-write - every other man page has the command line
> options fairly close to the start, not a few dozen screens in.

There should be a HOWTO and the reference manual page. Currently it's all
mixed into one large document; OTOH the problem is that two documents means
doubled effort of keeping things up to date.

Best,
Matthias

Re: [fetchmail-devel] FAQ re-write

[Rob M. <rob...@gm...>]

On 8/22/07, Matthias Andree <mat...@gm...> wrote:
>
> It is accessible, check <http://developer.berlios.de/wiki/?group_id=1824> -
> not much there yet except some internal development stuff that is outdated...

I'm having a look just now.

> There should be a HOWTO and the reference manual page. Currently it's all
> mixed into one large document; OTOH the problem is that two documents means
> doubled effort of keeping things up to date.

I don't see that there should be a huge amount of overlap between
these.  I assume the man page would cover the command line options and
the configuration file and the HowTo would largely consist of
configuration examples?

As for turning Wiki pages into HTML and/or PDF - neither look like
standard features of either the Berlios of PB Wikis.  Both conversions
however should be easy enough to automate/script (I've already written
some scripts to turn XML/HTML into PDF, based on HTMLDoc ISTR), though
I'm willing to be proven wrong :)

-- 
                 Please keep list traffic on the list.

Rob MacGregor
      Whoever fights monsters should see to it that in the process he
        doesn't become a monster.                  Friedrich Nietzsche

Re: [fetchmail-devel] FAQ re-write

[Matthias A. <mat...@gm...>]

On Wed, 22 Aug 2007, Rob MacGregor wrote:

> As for turning Wiki pages into HTML and/or PDF - neither look like
> standard features of either the Berlios of PB Wikis.  Both conversions
> however should be easy enough to automate/script (I've already written
> some scripts to turn XML/HTML into PDF, based on HTMLDoc ISTR), though
> I'm willing to be proven wrong :)

The (X)HTML -> PDF part is the easy one, there are several automated
ways to achieve that, HTMLDOC being one of the easiest and with very
reasonable result.

Well, the MoinMoin wiki engine has a command-line tool to export static
HTML pages, Timo Sirainen is using that for snapshotting the Dovecot
Wiki contents. (Dovecot is a fast combined IMAP/POP3+SSL server
supporting mbox and Maildir, among other useful features.)

If the Wiki can't export to HTML, perhaps we can stick to using a set
of HTML pages - it's easier to control quality that way, too: we don't
need to eyeball it constantly to avoid other people posting stupid
things (such as enclosing mda placeholders in single quotes, injecting
into sendmail with variable destination address or something).
I'm not at all against the concept of a Wiki, but I think some kind of
"peer review" to avoid stupidities should be inherent once we deal with
security sensitive stuff.

The HTML document is in SVN, and I think we (that means my asking Graham
Wilson) can arrange commit access for you, or we can just revive the
BerliOS SVN stuff to host the web site.

Best

-- 
Matthias Andree

Re: [fetchmail-devel] FAQ re-write

[Rob M. <rob...@gm...>]

On 8/23/07, Matthias Andree <mat...@gm...> wrote:
> On Wed, 22 Aug 2007, Rob MacGregor wrote:
<---SNIP--->
> Well, the MoinMoin wiki engine has a command-line tool to export static
> HTML pages, Timo Sirainen is using that for snapshotting the Dovecot
> Wiki contents. (Dovecot is a fast combined IMAP/POP3+SSL server
> supporting mbox and Maildir, among other useful features.)

That would certainly make life easier.

> If the Wiki can't export to HTML, perhaps we can stick to using a set
> of HTML pages - it's easier to control quality that way, too: we don't
> need to eyeball it constantly to avoid other people posting stupid
> things (such as enclosing mda placeholders in single quotes, injecting
> into sendmail with variable destination address or something).
> I'm not at all against the concept of a Wiki, but I think some kind of
> "peer review" to avoid stupidities should be inherent once we deal with
> security sensitive stuff.

If we go the wiki route then it would have to support (at least) 2
levels of users - admins (those you trust not to stuff up the
documentation) and everybody else (who have read only access).

Looking at the MoinMoin wiki documentation it does support that, plus
email notifications about page edits.

As for peer review, presumably such discussions could take place via
email, or even via Talk pages in the wiki?

> The HTML document is in SVN, and I think we (that means my asking Graham
> Wilson) can arrange commit access for you, or we can just revive the
> BerliOS SVN stuff to host the web site.

Well, getting up and running with SVN wouldn't be terribly difficult,
so that's always an option.

I'll admit that I'm looking for a solution that involves the minimal
amount of effort post-edit - I'm lazy but at least I know it ;)

-- 
                 Please keep list traffic on the list.

Rob MacGregor
      Whoever fights monsters should see to it that in the process he
        doesn't become a monster.                  Friedrich Nietzsche