Re: [Openvpn-devel] [Openvpn-users] OpenVPN documentation (man page) review

2011-01-13 Thread David Sommerseth 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 13/01/11 14:10, Samuli Seppänen wrote:
> 
>>
>> It should be possible to write a little script which parses the wiki
>> (page content) source text and makes man/html pages and example files
>> based on this.  This could be done before each release.
>>
>> The drawback is that the wiki markup might be too flexible (too many
>> features) and the parsing script might get complicated.
> I'm pretty sure we can get the Wiki contents out in HTML format. And
> there should be plenty of "HTML -> something" converters out there.
> 

It will probably be just as easy as parsing the wiki markup as the HTML
result.  That parsing code already exists somewhere in Trac.

The problem I was more thinking of is to have a style/layout which
matches man pages, f.ex.  There are certain elements which are required,
and a certain order.  And there are certain things which are not so
easily accessible in man, like how to center text, bullet lists, misc
indentation stuff.

There are several and different "tags" in *roff which are rather
limited, but they work flawlessly when used correctly, in the strict
manner they was designed for.  Wiki-markup/HTML is way more flexible.
Or to say it another way, converting *roff -> HTML is easy as going
downhill, HTML -> *roff is more like going uphill.

However - nothing is impossible, it just takes a bit longer time :)


kind regards,

David Sommerseth
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/

iEYEARECAAYFAk0vF/gACgkQDC186MBRfrqO4QCdFzSN7NEbuMkL78TpOE8Ki/H0
zA8AoJe62qdFM25XUK4WjFvSfhhKqXlb
=+NCV
-END PGP SIGNATURE-

Re: [Openvpn-devel] OpenVPN documentation (man page) review

2011-01-13 Thread Samuli Seppänen 

>
> It should be possible to write a little script which parses the wiki
> (page content) source text and makes man/html pages and example files
> based on this.  This could be done before each release.
>
> The drawback is that the wiki markup might be too flexible (too many
> features) and the parsing script might get complicated.
I'm pretty sure we can get the Wiki contents out in HTML format. And
there should be plenty of "HTML -> something" converters out there.

-- 
Samuli Seppänen
Community Manager
OpenVPN Technologies, Inc

irc freenode net: mattock

Re: [Openvpn-devel] OpenVPN documentation (man page) review

2011-01-13 Thread David Sommerseth 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 12/01/11 21:48, Jan Just Keijser wrote:
> Hi David,
> 
> David Sommerseth wrote:
>> -BEGIN PGP SIGNED MESSAGE-
>> Hash: SHA1
>>
>>
>> Hi folks!
>>
>> This is a little cry for help from us playing with the OpenVPN code.
>>
>> We have a quite good man page today with a lot of information.  But
>> maintaining it and to make sure it is up-to-date with all the features
>> OpenVPN supports is often not high up on the priority list.  In
>> addition, the current format (one single file, in pure man page format)
>> is getting harder and harder to maintain as well.
>>
>> So, we're hoping some people with some English skills is interested to
>> help out improving this situation.  What we immediately would like to
>> see is something along these lines:
>>
>> * Move the man page to a better format than the pure man page format.
>>   Are there some good tools/formats like ascii2man or DocBookXML which
>>   could help easing the maintenance of our documentation?
>>
>> * Split up the documentation into more focused sections, like
>>   - main openvpn page (kind of like openvpn.8 today)
>>   Gives an executive overview over OpenVPN, features and references
>>   to the other documentation pages.  A bonus would be if it easily
>>   can produce other formats in addition, like HTML, PS/PDF, ePub.
>>
>>   - openvpn common options
>>   Gives information about the common options openvpn has, which is
>>   useful on both server and client instances.  F.ex. --keepalive,
>>   --tls-auth, --cert, --key, --ca, etc
>>
>>   - openvpn server options
>>   Describes only the options which are relevant for openvpn servers
>>
>>   - openvpn client options
>>   Describes only options useful for openvpn clients
>>
>>   - openvpn plug-ins
>>   Describes the different script plug-in hooks and environment
>>   variables available to scripts and plug-ins written in C
>>
>> * Review the contents of all the documentation, check their accuracy
>>   - Make sure no options are not available in OpenVPN 2.2 or later
>>   - Make sure no options are missing in the documentation, which is
>> available in the source code  (options.c is a good reference)
>>
>> * Review and check if all external references
>>   - Make sure all references to external sources, like web-sites, are
>> still available, valid and relevant in the document context
>>   - Find other external resources which are worth including.
>>
>> (These points are not carved into stone, but is more like a guideline of
>> what needs to be considered)
>>
>> This task should hopefully not require too much in-depth development
>> knowledge.  It should be user-focused, so that we avoid using terms and
>> details which is not so easy to understand.  What I'm saying is that
>> this documentation can be more useful and readable if users are involved
>> in this process.
>>
>> If someone are willing to step up and take a lead, that would be great!
>>  Further, discussions and reviews of the document changes should
>> probably happen on the openvpn-users mailing list.  That way, it might
>> be easier for users to review the documentation and provide feedback.
>>
>> We don't want this to just be a solo-project from someone in our OpenVPN
>> community, so we hope more people can help out and contribute, also if
>> you don't consider yourself a developer.
>>   
> I'd be willing to contribute but I don't see myself leading this effort
> right now (due to other obligations).

That's just fine!  And I presume you're not the only one loaded with
other tasks.  I believe if every one contributes a little bit according
to available time, big efforts will be achieved in the end.  Just
reading suggestions and giving comments are also much appreciated!

> As for the document format: if we want users to contribute then we
> should not opt for a too-difficult format that users would have to learn
> before being able to contribute. Docbook and/or texinfo are nice for
> Linux users but you'd scare away most Windows/Mac users.
> What about plain simple OpenDoc (odf) ?

I've been thinking about that we need to lower the level for
contributing documentation.  ODF isn't such a bad suggestion, after all
it is XML based and with strict style usage it should be possible to do
some script magic on these files.  However, why not lower the bar even
more?  (And I do see Karl O. Pinc's comment as well, people would need
to install ODF compliant software)

Krzee on IRC simply asked, why not use wiki for this purpose?  I
personally think that is a very good idea!  For the reasons:

* Simple formatting but still some structured way of organising the
  contents
* Many users are familiar with wikis, and the learning curve is usually
  low.
* No special software required, all you need is a browser
* No git knowledge needed
* Revision control is built into the wiki (and on community wiki, login
  is required - so we can trace who did what)

[Openvpn-devel] Topics for today's meeting

2011-01-13 Thread Samuli Seppänen 
Hi,

We're having an IRC meeting today, starting at 18:00 UTC on
#openvpn-de...@irc.freenode.net. Current topic list is here:



If you have any other things you'd like to bring up, respond to this
mail, send me mail privately or add them to the list yourself.

-- 
Samuli Seppänen
Community Manager
OpenVPN Technologies, Inc

irc freenode net: mattock

Re: [Openvpn-devel] [Openvpn-users] OpenVPN documentation (man page) review

2011-01-13 Thread Samuli Seppänen 

> On 01/12/2011 02:48:29 PM, Jan Just Keijser wrote:
>
>   
>> As for the document format: if we want users to contribute then we 
>> should not opt for a too-difficult format that users would have to
>> learn 
>> before being able to contribute. Docbook and/or texinfo are nice for 
>> Linux users but you'd scare away most Windows/Mac users.
>> What about plain simple OpenDoc (odf) ?
>> 
>
> If you say so.  (It's not as if they haven't seen html,
> which is superficially similar to docbook/xml,
> or haven't they?)  But they could install and use lyx
> and get a full-gui experience.  They'll have to install
> something anyway if they want to use odf.
>
>   
I think the most straightforward option for users would be to use the
Trac Wiki: this option was discussed in the #openvpn-devel a while back.
Trac is probably not the optimal tool from formatting perspective, but
I'm pretty sure it's easiest method to add or change content. Users
would only need to know some of Trac's wiki syntax without of having to
learn things such as:

- Git/version control basics
- Docbook/xml/man/roff/whatever syntax
- basics of patching
- how our development process works

I'm pretty sure there are many who are not familiar with any of the
above, but could still contribute to the documentation. We'd obviously
need to make sure that the wiki pages can be exported in some useful format.

Any thoughts?

-- 
Samuli Seppänen
Community Manager
OpenVPN Technologies, Inc

irc freenode net: mattock