[Caml-list] OCaml wiki

[Caml-list] OCaml wiki

[Wojciech Meyer]

Hi,

These days ocaml.org is a great resource and starting point for the
community and people interested in learning OCaml. It would be great
however if we have a collective wiki for OCaml too. Not being here at
any rate competitive and just complementary.

It could cover:
- using core toolchain
- tooling like Oasis, OPAM, ocamlfind, ocamlbuild etc.
- type system tricks
- small projects with good code examples
- tools settings, emacs & vim configuration snippets
etc.

it should be searchable, and fairly centralised.

What kind of wiki engine we would like to use?

I'd just opt either for oddmuse, mediawiki perhaps with some movement
towards custom one based on Ocsigen and Eliom, but here I don't have any
strong opinions, feel free to propose anything else.

Separate issue is storage and server etc., I'd happily organise/discuss
these things, once we know the details :-)

I'm open for any ideas and people joining up with the effort.

Thanks,

-Wojciech

Re: [Caml-list] OCaml wiki

[Malcolm Matalka]

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

I think it's a swell idea. Perhaps post to the infrastructure mailing list
to see what these running the site feel most comfortable with.

/M
On Dec 21, 2012 12:15 AM, "Wojciech Meyer" <wojciech.meyer@gmail.com> wrote:

> Hi,
>
> These days ocaml.org is a great resource and starting point for the
> community and people interested in learning OCaml. It would be great
> however if we have a collective wiki for OCaml too. Not being here at
> any rate competitive and just complementary.
>
> It could cover:
> - using core toolchain
> - tooling like Oasis, OPAM, ocamlfind, ocamlbuild etc.
> - type system tricks
> - small projects with good code examples
> - tools settings, emacs & vim configuration snippets
> etc.
>
> it should be searchable, and fairly centralised.
>
> What kind of wiki engine we would like to use?
>
> I'd just opt either for oddmuse, mediawiki perhaps with some movement
> towards custom one based on Ocsigen and Eliom, but here I don't have any
> strong opinions, feel free to propose anything else.
>
> Separate issue is storage and server etc., I'd happily organise/discuss
> these things, once we know the details :-)
>
> I'm open for any ideas and people joining up with the effort.
>
> Thanks,
>
> -Wojciech
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>

[-- Attachment #2: Type: text/html, Size: 2150 bytes --]

Re: [Caml-list] OCaml wiki

[Anil Madhavapeddy]

Personally, I've got mixed feelings about wikis from experience with
previous projects, since they get out of date very rapidly indeed. They
do work well if someone's maintaining it, but if that's the case, why
not just push these tips and guides to the existing ocaml.org site?

I'm happy to run a wiki on the OCL infrastructure, but would strongly
prefer contributions to the ocaml.org Git repo with all this good stuff
instead!  If it really turns out we need a swanky wiki, that can be arranged
later...

-anil

On 20 Dec 2012, at 23:15, Wojciech Meyer <wojciech.meyer@gmail.com> wrote:

> Hi,
> 
> These days ocaml.org is a great resource and starting point for the
> community and people interested in learning OCaml. It would be great
> however if we have a collective wiki for OCaml too. Not being here at
> any rate competitive and just complementary.
> 
> It could cover:
> - using core toolchain
> - tooling like Oasis, OPAM, ocamlfind, ocamlbuild etc.
> - type system tricks
> - small projects with good code examples
> - tools settings, emacs & vim configuration snippets
> etc.
> 
> it should be searchable, and fairly centralised.
> 
> What kind of wiki engine we would like to use?
> 
> I'd just opt either for oddmuse, mediawiki perhaps with some movement
> towards custom one based on Ocsigen and Eliom, but here I don't have any
> strong opinions, feel free to propose anything else.
> 
> Separate issue is storage and server etc., I'd happily organise/discuss
> these things, once we know the details :-)
> 
> I'm open for any ideas and people joining up with the effort.
> 
> Thanks,
> 
> -Wojciech
> 
> -- 
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
> 

Re: [Caml-list] OCaml wiki

[Benedikt Meurer]

On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:

> Personally, I've got mixed feelings about wikis from experience with
> previous projects, since they get out of date very rapidly indeed. They
> do work well if someone's maintaining it, but if that's the case, why
> not just push these tips and guides to the existing ocaml.org site?
> 
> I'm happy to run a wiki on the OCL infrastructure, but would strongly
> prefer contributions to the ocaml.org Git repo with all this good stuff
> instead!  If it really turns out we need a swanky wiki, that can be arranged
> later...

Why not use the wiki provided by Github for the ocaml.org project?

> -anil

Benedikt

Re: [Caml-list] OCaml wiki

[Anil Madhavapeddy]

On 20 Dec 2012, at 23:31, Benedikt Meurer <benedikt.meurer@googlemail.com> wrote:
> 
> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
> 
>> Personally, I've got mixed feelings about wikis from experience with
>> previous projects, since they get out of date very rapidly indeed. They
>> do work well if someone's maintaining it, but if that's the case, why
>> not just push these tips and guides to the existing ocaml.org site?
>> 
>> I'm happy to run a wiki on the OCL infrastructure, but would strongly
>> prefer contributions to the ocaml.org Git repo with all this good stuff
>> instead!  If it really turns out we need a swanky wiki, that can be arranged
>> later...
> 
> Why not use the wiki provided by Github for the ocaml.org project?

That works too; Thomas has written a Github Markdown to HTML converter in
COW [1], and is using that to generate the OPAM website from the Github
wiki (for the documentation that you see on opam.ocamlpro.com).

[1] http://github.com/mirage/ocaml-cow

Re: [Caml-list] OCaml wiki

[Malcolm Matalka]

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

Does the github wiki just apply to the github project or can it be themed
and the likes to look like the ocaml page?

At the very least some list of page ideas would be great, it can be hard to
know if the information each of us have in our head is information people
want.
On Dec 21, 2012 12:34 AM, "Anil Madhavapeddy" <anil@recoil.org> wrote:

> On 20 Dec 2012, at 23:31, Benedikt Meurer <benedikt.meurer@googlemail.com>
> wrote:
> >
> > On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
> >
> >> Personally, I've got mixed feelings about wikis from experience with
> >> previous projects, since they get out of date very rapidly indeed. They
> >> do work well if someone's maintaining it, but if that's the case, why
> >> not just push these tips and guides to the existing ocaml.org site?
> >>
> >> I'm happy to run a wiki on the OCL infrastructure, but would strongly
> >> prefer contributions to the ocaml.org Git repo with all this good stuff
> >> instead!  If it really turns out we need a swanky wiki, that can be
> arranged
> >> later...
> >
> > Why not use the wiki provided by Github for the ocaml.org project?
>
> That works too; Thomas has written a Github Markdown to HTML converter in
> COW [1], and is using that to generate the OPAM website from the Github
> wiki (for the documentation that you see on opam.ocamlpro.com).
>
> [1] http://github.com/mirage/ocaml-cow
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs

[-- Attachment #2: Type: text/html, Size: 2629 bytes --]

Re: [Caml-list] OCaml wiki

[Wojciech Meyer]

Anil Madhavapeddy <anil@recoil.org> writes:

> On 20 Dec 2012, at 23:31, Benedikt Meurer <benedikt.meurer@googlemail.com> wrote:
>>
>> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
>>
>>> Personally, I've got mixed feelings about wikis from experience with
>>> previous projects, since they get out of date very rapidly indeed. They
>>> do work well if someone's maintaining it, but if that's the case, why
>>> not just push these tips and guides to the existing ocaml.org site?
>>>
>>> I'm happy to run a wiki on the OCL infrastructure, but would strongly
>>> prefer contributions to the ocaml.org Git repo with all this good stuff
>>> instead!  If it really turns out we need a swanky wiki, that can be arranged
>>> later...
>>
>> Why not use the wiki provided by Github for the ocaml.org project?
>
> That works too; Thomas has written a Github Markdown to HTML converter in
> COW [1], and is using that to generate the OPAM website from the Github
> wiki (for the documentation that you see on opam.ocamlpro.com).

Yes, we could use github pages as long as they are searchable, I see no
problem with it. I think the biggest advantage of wiki would be that
everything would be in single place and hyperlinked.

As for protecting the wiki from being up-date emacswiki [1] is always a
great example that it is possible as long as people maintain their
webpages. Also, I feel that ocaml.org pages on github would be a good
entry point.

[1] http://emacswiki.org/

-Wojciech

[Caml-list] OCaml search into libraries for ocaml.org

[Francois Berenger]

Hello,

About ocaml.org: Wojciech Meyer just asked for a Wiki.

In addition to this, as a programmer, I am especially interested
into being able to search into OCaml libraries via a search engine.

A simple engine as in the left of this page:
http://projects.camlcity.org/projects/ocamlnet.html
is already useful.

However, I'd like the search engine to be able to
do search by type queries, "a la" Hoogle and as in:
http://search.ocaml.jp/

But it should index more libraries. For example, all
packages available in OPAM.

Regards,
F.

Re: [Caml-list] OCaml wiki

[Ashish Agarwal]

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

A wiki could be good but I strongly encourage any such effort to integrate
with ocaml.org, and to carefully weigh the pros and cons. Wikis make
contributions easier, but you need someone to keep the content organized
and do some basic quality control. Also, the structure of the documentation
is not very customizable. The question is whether pushing to a git repo
(the current contribution method for ocaml.org) is so much harder (given
that we're all programmers after all).

The tutorials page is a good candidate for converting to wiki format, but
remember that a wiki is where all this content came from, and it eventually
got out of date. We could create wiki.ocaml.org, but then the question is
how to make it integrate nicely with the rest of the pages that don't fit
the wiki model.

Finally, which wiki software to use? None are very good, and who amongst us
is keen to hack into php code. My initial goal for ocaml.org was to use
ocsigen and ocsimore, but there is a big upfront cost in getting such a
site implemented.

Whatever the community decides, we can support and integrate with ocaml.org.
My only strong opinion is please don't build a separate unrelated site,
with duplication of effort and and fragmentation of content.


On Thu, Dec 20, 2012 at 6:50 PM, Wojciech Meyer <wojciech.meyer@gmail.com>wrote:

> Anil Madhavapeddy <anil@recoil.org> writes:
>
> > On 20 Dec 2012, at 23:31, Benedikt Meurer <
> benedikt.meurer@googlemail.com> wrote:
> >>
> >> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
> >>
> >>> Personally, I've got mixed feelings about wikis from experience with
> >>> previous projects, since they get out of date very rapidly indeed. They
> >>> do work well if someone's maintaining it, but if that's the case, why
> >>> not just push these tips and guides to the existing ocaml.org site?
> >>>
> >>> I'm happy to run a wiki on the OCL infrastructure, but would strongly
> >>> prefer contributions to the ocaml.org Git repo with all this good
> stuff
> >>> instead!  If it really turns out we need a swanky wiki, that can be
> arranged
> >>> later...
> >>
> >> Why not use the wiki provided by Github for the ocaml.org project?
> >
> > That works too; Thomas has written a Github Markdown to HTML converter in
> > COW [1], and is using that to generate the OPAM website from the Github
> > wiki (for the documentation that you see on opam.ocamlpro.com).
>
> Yes, we could use github pages as long as they are searchable, I see no
> problem with it. I think the biggest advantage of wiki would be that
> everything would be in single place and hyperlinked.
>
> As for protecting the wiki from being up-date emacswiki [1] is always a
> great example that it is possible as long as people maintain their
> webpages. Also, I feel that ocaml.org pages on github would be a good
> entry point.
>
> [1] http://emacswiki.org/
>
> -Wojciech
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>

[-- Attachment #2: Type: text/html, Size: 4708 bytes --]

Re: [Caml-list] OCaml search into libraries for ocaml.org

[Ashish Agarwal]

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

This is certainly on many people's mind, and various projects are working
towards making this happen. There are a few requirements to make it work:

* we need a master blessed list of libraries, e.g. the OCamlPro version of
the opam-repository
* a make doc command that works for every one of these libraries

Then, we could create a section on ocaml.org with API documentation for
every library automatically updated nightly.


On Thu, Dec 20, 2012 at 8:31 PM, Francois Berenger <berenger@riken.jp>wrote:

> Hello,
>
> About ocaml.org: Wojciech Meyer just asked for a Wiki.
>
> In addition to this, as a programmer, I am especially interested
> into being able to search into OCaml libraries via a search engine.
>
> A simple engine as in the left of this page:
> http://projects.camlcity.org/**projects/ocamlnet.html<http://projects.camlcity.org/projects/ocamlnet.html>
> is already useful.
>
> However, I'd like the search engine to be able to
> do search by type queries, "a la" Hoogle and as in:
> http://search.ocaml.jp/
>
> But it should index more libraries. For example, all
> packages available in OPAM.
>
> Regards,
> F.
>
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/**arc/caml-list<https://sympa.inria.fr/sympa/arc/caml-list>
> Beginner's list: http://groups.yahoo.com/group/**ocaml_beginners<http://groups.yahoo.com/group/ocaml_beginners>
> Bug reports: http://caml.inria.fr/bin/caml-**bugs<http://caml.inria.fr/bin/caml-bugs>
>

[-- Attachment #2: Type: text/html, Size: 2261 bytes --]

Re: [Caml-list] OCaml search into libraries for ocaml.org

[forum]

Le 21 déc. 2012 à 03:57, Ashish Agarwal a écrit :

> This is certainly on many people's mind, and various projects are working towards making this happen. There are a few requirements to make it work:
> 
> * we need a master blessed list of libraries, e.g. the OCamlPro version of the opam-repository
> * a make doc command that works for every one of these libraries
> 
> Then, we could create a section on ocaml.org with API documentation for every library automatically updated nightly.

For the record, I plan to extend Argot to be able to merge the data
produced by different runs. You can see how Argot works on the
standard library at the following address:
	http://argot.x9c.fr/distrib/argot-4.00-libref-frame/argot_index.html

Currently the information is dumped as JavaScript calls to functions
allowing to populate data structures. Now, one of the question is
about the output format(s). From the top of my head:
  - json / xml, acting as lingua franca linking with other tools;
  - OCaml marshal format, enabling easy use from OCaml programs;
  - SQL insert commands, allowing to populate a database.

I would be glad to get advice on this question, and also
possible feature requests about Argot, whose homepage is:
	http://argot.x9c.fr


Kind regards,

Xavier Clerc

Re: [Caml-list] OCaml wiki

[Philippe Veber]

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

For what it's worth, my opinion is also that we should focus our efforts on
the website, especially now that we have something that we can be proud of
(kudos to all those behind ocaml.org). As the development of the website
showed very well, it takes a really high amount of time and tenacious work
to do something useful *and* acknowledged. I think there is a limited
man-power in the community to advertise and document our favorite language,
let's not split it up but rather pour it into a single, high-quality and
carefully reviewed contents. I feel the best achievement of ocaml.org is to
exist as a central place where to add ocaml material, improving the
readability of ocaml as a whole, and the visibility of ocaml projects.
Pushing to a git repo is more difficult than adding stuff on a wiki, but we
nerds don't really care about that, right ;o)?

So yes, the only benefit I see for the wiki is to lower the barrier for
contributions. It is true (I tried this morning) that it is not
straightforward to contribute to the site for those who do not use opam and
git everyday (not to mention that you have to know HTML basics). But with a
proper documentation, using git to contribute the website is not so
difficult, and has lots of (editorial) benefits. Plus that way we help
people to learn those anyway useful technologies. Unless someone wants to
write it, I can have a try at writing a page "Contributing to ocaml.org" (I
couldn't see such a page on the website).



2012/12/21 Ashish Agarwal <agarwal1975@gmail.com>

> A wiki could be good but I strongly encourage any such effort to integrate
> with ocaml.org, and to carefully weigh the pros and cons. Wikis make
> contributions easier, but you need someone to keep the content organized
> and do some basic quality control. Also, the structure of the documentation
> is not very customizable. The question is whether pushing to a git repo
> (the current contribution method for ocaml.org) is so much harder (given
> that we're all programmers after all).
>
> The tutorials page is a good candidate for converting to wiki format, but
> remember that a wiki is where all this content came from, and it eventually
> got out of date. We could create wiki.ocaml.org, but then the question is
> how to make it integrate nicely with the rest of the pages that don't fit
> the wiki model.
>
> Finally, which wiki software to use? None are very good, and who amongst
> us is keen to hack into php code. My initial goal for ocaml.org was to
> use ocsigen and ocsimore, but there is a big upfront cost in getting such a
> site implemented.
>
> Whatever the community decides, we can support and integrate with
> ocaml.org. My only strong opinion is please don't build a separate
> unrelated site, with duplication of effort and and fragmentation of content.
>
>
> On Thu, Dec 20, 2012 at 6:50 PM, Wojciech Meyer <wojciech.meyer@gmail.com>wrote:
>
>> Anil Madhavapeddy <anil@recoil.org> writes:
>>
>> > On 20 Dec 2012, at 23:31, Benedikt Meurer <
>> benedikt.meurer@googlemail.com> wrote:
>> >>
>> >> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
>> >>
>> >>> Personally, I've got mixed feelings about wikis from experience with
>> >>> previous projects, since they get out of date very rapidly indeed.
>> They
>> >>> do work well if someone's maintaining it, but if that's the case, why
>> >>> not just push these tips and guides to the existing ocaml.org site?
>> >>>
>> >>> I'm happy to run a wiki on the OCL infrastructure, but would strongly
>> >>> prefer contributions to the ocaml.org Git repo with all this good
>> stuff
>> >>> instead!  If it really turns out we need a swanky wiki, that can be
>> arranged
>> >>> later...
>> >>
>> >> Why not use the wiki provided by Github for the ocaml.org project?
>> >
>> > That works too; Thomas has written a Github Markdown to HTML converter
>> in
>> > COW [1], and is using that to generate the OPAM website from the Github
>> > wiki (for the documentation that you see on opam.ocamlpro.com).
>>
>> Yes, we could use github pages as long as they are searchable, I see no
>> problem with it. I think the biggest advantage of wiki would be that
>> everything would be in single place and hyperlinked.
>>
>> As for protecting the wiki from being up-date emacswiki [1] is always a
>> great example that it is possible as long as people maintain their
>> webpages. Also, I feel that ocaml.org pages on github would be a good
>> entry point.
>>
>> [1] http://emacswiki.org/
>>
>> -Wojciech
>>
>> --
>> Caml-list mailing list.  Subscription management and archives:
>> https://sympa.inria.fr/sympa/arc/caml-list
>> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>> Bug reports: http://caml.inria.fr/bin/caml-bugs
>>
>
>

[-- Attachment #2: Type: text/html, Size: 6773 bytes --]

Re: [Caml-list] OCaml wiki

[Fermin Reig]

For what it's worth, haskell.org is a wiki and the contents is of good 
quality and well organised. Guidelines for contributing are available at 
http://www.haskell.org/haskellwiki/HaskellWiki:Contributing

On 21/12/12 08:37, Philippe Veber wrote:
> For what it's worth, my opinion is also that we should focus our 
> efforts on the website, especially now that we have something that we 
> can be proud of (kudos to all those behind ocaml.org 
> <http://ocaml.org>). As the development of the website showed very 
> well, it takes a really high amount of time and tenacious work to do 
> something useful *and* acknowledged. I think there is a limited 
> man-power in the community to advertise and document our favorite 
> language, let's not split it up but rather pour it into a single, 
> high-quality and carefully reviewed contents. I feel the best 
> achievement of ocaml.org <http://ocaml.org> is to exist as a central 
> place where to add ocaml material, improving the readability of ocaml 
> as a whole, and the visibility of ocaml projects. Pushing to a git 
> repo is more difficult than adding stuff on a wiki, but we nerds don't 
> really care about that, right ;o)?
>
> So yes, the only benefit I see for the wiki is to lower the barrier 
> for contributions. It is true (I tried this morning) that it is not 
> straightforward to contribute to the site for those who do not use 
> opam and git everyday (not to mention that you have to know HTML 
> basics). But with a proper documentation, using git to contribute the 
> website is not so difficult, and has lots of (editorial) benefits. 
> Plus that way we help people to learn those anyway useful 
> technologies. Unless someone wants to write it, I can have a try at 
> writing a page "Contributing to ocaml.org <http://ocaml.org>" (I 
> couldn't see such a page on the website).
>
>
>
> 2012/12/21 Ashish Agarwal <agarwal1975@gmail.com 
> <mailto:agarwal1975@gmail.com>>
>
>     A wiki could be good but I strongly encourage any such effort to
>     integrate with ocaml.org <http://ocaml.org>, and to carefully
>     weigh the pros and cons. Wikis make contributions easier, but you
>     need someone to keep the content organized and do some basic
>     quality control. Also, the structure of the documentation is not
>     very customizable. The question is whether pushing to a git repo
>     (the current contribution method for ocaml.org <http://ocaml.org>)
>     is so much harder (given that we're all programmers after all).
>
>     The tutorials page is a good candidate for converting to wiki
>     format, but remember that a wiki is where all this content came
>     from, and it eventually got out of date. We could create
>     wiki.ocaml.org <http://wiki.ocaml.org>, but then the question is
>     how to make it integrate nicely with the rest of the pages that
>     don't fit the wiki model.
>
>     Finally, which wiki software to use? None are very good, and who
>     amongst us is keen to hack into php code. My initial goal for
>     ocaml.org <http://ocaml.org> was to use ocsigen and ocsimore, but
>     there is a big upfront cost in getting such a site implemented.
>
>     Whatever the community decides, we can support and integrate with
>     ocaml.org <http://ocaml.org>. My only strong opinion is please
>     don't build a separate unrelated site, with duplication of effort
>     and and fragmentation of content.
>
>
>     On Thu, Dec 20, 2012 at 6:50 PM, Wojciech Meyer
>     <wojciech.meyer@gmail.com <mailto:wojciech.meyer@gmail.com>> wrote:
>
>         Anil Madhavapeddy <anil@recoil.org <mailto:anil@recoil.org>>
>         writes:
>
>         > On 20 Dec 2012, at 23:31, Benedikt Meurer
>         <benedikt.meurer@googlemail.com
>         <mailto:benedikt.meurer@googlemail.com>> wrote:
>         >>
>         >> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy
>         <anil@recoil.org <mailto:anil@recoil.org>> wrote:
>         >>
>         >>> Personally, I've got mixed feelings about wikis from
>         experience with
>         >>> previous projects, since they get out of date very rapidly
>         indeed. They
>         >>> do work well if someone's maintaining it, but if that's
>         the case, why
>         >>> not just push these tips and guides to the existing
>         ocaml.org <http://ocaml.org> site?
>         >>>
>         >>> I'm happy to run a wiki on the OCL infrastructure, but
>         would strongly
>         >>> prefer contributions to the ocaml.org <http://ocaml.org>
>         Git repo with all this good stuff
>         >>> instead!  If it really turns out we need a swanky wiki,
>         that can be arranged
>         >>> later...
>         >>
>         >> Why not use the wiki provided by Github for the ocaml.org
>         <http://ocaml.org> project?
>         >
>         > That works too; Thomas has written a Github Markdown to HTML
>         converter in
>         > COW [1], and is using that to generate the OPAM website from
>         the Github
>         > wiki (for the documentation that you see on
>         opam.ocamlpro.com <http://opam.ocamlpro.com>).
>
>         Yes, we could use github pages as long as they are searchable,
>         I see no
>         problem with it. I think the biggest advantage of wiki would
>         be that
>         everything would be in single place and hyperlinked.
>
>         As for protecting the wiki from being up-date emacswiki [1] is
>         always a
>         great example that it is possible as long as people maintain their
>         webpages. Also, I feel that ocaml.org <http://ocaml.org> pages
>         on github would be a good
>         entry point.
>
>         [1] http://emacswiki.org/
>
>         -Wojciech
>
>         --
>         Caml-list mailing list.  Subscription management and archives:
>         https://sympa.inria.fr/sympa/arc/caml-list
>         Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>         Bug reports: http://caml.inria.fr/bin/caml-bugs
>
>
>

Re: [Caml-list] OCaml wiki

[Philippe Veber]

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

Of course you can do good stuff with a wiki! I was not arguing that a wiki
is not an adequate medium to build a website, but rather that we should not
duplicate our efforts. I think building a site of good quality and well
organised is a lot of work *whatever* the technology you're relying on (not
to mention, the time to get it accepted) The site ocaml.org is built with
templated HTML and stored on github, this is one possible technical choice
where contributions are easy to make if the procedure is documented
properly. Right now I see no compelling argument to start a wiki, and just
argued that we should first focus on the website. Maybe after some time
(and hopefully many contributions :o)!), it will become evident that we
need something else (maybe a wiki), but right now I find it risky to split
our efforts in several community projects. Sorry if my previous message was
not clear, and thanks for the pointer to the guidelines!

2012/12/21 Fermin Reig <ferminreig@fastmail.fm>

> For what it's worth, haskell.org is a wiki and the contents is of good
> quality and well organised. Guidelines for contributing are available at
> http://www.haskell.org/**haskellwiki/HaskellWiki:**Contributing<http://www.haskell.org/haskellwiki/HaskellWiki:Contributing>
>
> On 21/12/12 08:37, Philippe Veber wrote:
>
>> For what it's worth, my opinion is also that we should focus our efforts
>> on the website, especially now that we have something that we can be proud
>> of (kudos to all those behind ocaml.org <http://ocaml.org>). As the
>> development of the website showed very well, it takes a really high amount
>> of time and tenacious work to do something useful *and* acknowledged. I
>> think there is a limited man-power in the community to advertise and
>> document our favorite language, let's not split it up but rather pour it
>> into a single, high-quality and carefully reviewed contents. I feel the
>> best achievement of ocaml.org <http://ocaml.org> is to exist as a
>> central place where to add ocaml material, improving the readability of
>> ocaml as a whole, and the visibility of ocaml projects. Pushing to a git
>> repo is more difficult than adding stuff on a wiki, but we nerds don't
>> really care about that, right ;o)?
>>
>> So yes, the only benefit I see for the wiki is to lower the barrier for
>> contributions. It is true (I tried this morning) that it is not
>> straightforward to contribute to the site for those who do not use opam and
>> git everyday (not to mention that you have to know HTML basics). But with a
>> proper documentation, using git to contribute the website is not so
>> difficult, and has lots of (editorial) benefits. Plus that way we help
>> people to learn those anyway useful technologies. Unless someone wants to
>> write it, I can have a try at writing a page "Contributing to ocaml.org <
>> http://ocaml.org>" (I couldn't see such a page on the website).
>>
>>
>>
>> 2012/12/21 Ashish Agarwal <agarwal1975@gmail.com <mailto:
>> agarwal1975@gmail.com>**>
>>
>>
>>     A wiki could be good but I strongly encourage any such effort to
>>     integrate with ocaml.org <http://ocaml.org>, and to carefully
>>
>>     weigh the pros and cons. Wikis make contributions easier, but you
>>     need someone to keep the content organized and do some basic
>>     quality control. Also, the structure of the documentation is not
>>     very customizable. The question is whether pushing to a git repo
>>     (the current contribution method for ocaml.org <http://ocaml.org>)
>>
>>     is so much harder (given that we're all programmers after all).
>>
>>     The tutorials page is a good candidate for converting to wiki
>>     format, but remember that a wiki is where all this content came
>>     from, and it eventually got out of date. We could create
>>     wiki.ocaml.org <http://wiki.ocaml.org>, but then the question is
>>
>>     how to make it integrate nicely with the rest of the pages that
>>     don't fit the wiki model.
>>
>>     Finally, which wiki software to use? None are very good, and who
>>     amongst us is keen to hack into php code. My initial goal for
>>     ocaml.org <http://ocaml.org> was to use ocsigen and ocsimore, but
>>
>>     there is a big upfront cost in getting such a site implemented.
>>
>>     Whatever the community decides, we can support and integrate with
>>     ocaml.org <http://ocaml.org>. My only strong opinion is please
>>
>>     don't build a separate unrelated site, with duplication of effort
>>     and and fragmentation of content.
>>
>>
>>     On Thu, Dec 20, 2012 at 6:50 PM, Wojciech Meyer
>>     <wojciech.meyer@gmail.com <mailto:wojciech.meyer@gmail.**com<wojciech.meyer@gmail.com>>>
>> wrote:
>>
>>         Anil Madhavapeddy <anil@recoil.org <mailto:anil@recoil.org>>
>>
>>         writes:
>>
>>         > On 20 Dec 2012, at 23:31, Benedikt Meurer
>>         <benedikt.meurer@googlemail.**com<benedikt.meurer@googlemail.com>
>>         <mailto:benedikt.meurer@**googlemail.com<benedikt.meurer@googlemail.com>>>
>> wrote:
>>         >>
>>         >> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy
>>         <anil@recoil.org <mailto:anil@recoil.org>> wrote:
>>         >>
>>         >>> Personally, I've got mixed feelings about wikis from
>>         experience with
>>         >>> previous projects, since they get out of date very rapidly
>>         indeed. They
>>         >>> do work well if someone's maintaining it, but if that's
>>         the case, why
>>         >>> not just push these tips and guides to the existing
>>         ocaml.org <http://ocaml.org> site?
>>
>>         >>>
>>         >>> I'm happy to run a wiki on the OCL infrastructure, but
>>         would strongly
>>         >>> prefer contributions to the ocaml.org <http://ocaml.org>
>>
>>         Git repo with all this good stuff
>>         >>> instead!  If it really turns out we need a swanky wiki,
>>         that can be arranged
>>         >>> later...
>>         >>
>>         >> Why not use the wiki provided by Github for the ocaml.org
>>         <http://ocaml.org> project?
>>
>>         >
>>         > That works too; Thomas has written a Github Markdown to HTML
>>         converter in
>>         > COW [1], and is using that to generate the OPAM website from
>>         the Github
>>         > wiki (for the documentation that you see on
>>         opam.ocamlpro.com <http://opam.ocamlpro.com>).
>>
>>
>>         Yes, we could use github pages as long as they are searchable,
>>         I see no
>>         problem with it. I think the biggest advantage of wiki would
>>         be that
>>         everything would be in single place and hyperlinked.
>>
>>         As for protecting the wiki from being up-date emacswiki [1] is
>>         always a
>>         great example that it is possible as long as people maintain their
>>         webpages. Also, I feel that ocaml.org <http://ocaml.org> pages
>>
>>         on github would be a good
>>         entry point.
>>
>>         [1] http://emacswiki.org/
>>
>>         -Wojciech
>>
>>         --
>>         Caml-list mailing list.  Subscription management and archives:
>>         https://sympa.inria.fr/sympa/**arc/caml-list<https://sympa.inria.fr/sympa/arc/caml-list>
>>         Beginner's list: http://groups.yahoo.com/group/**ocaml_beginners<http://groups.yahoo.com/group/ocaml_beginners>
>>         Bug reports: http://caml.inria.fr/bin/caml-**bugs<http://caml.inria.fr/bin/caml-bugs>
>>
>>
>>
>>
>

[-- Attachment #2: Type: text/html, Size: 10641 bytes --]

Re: [Caml-list] OCaml wiki

[Hezekiah M. Carty]

On Thu, Dec 20, 2012 at 6:31 PM, Benedikt Meurer
<benedikt.meurer@googlemail.com> wrote:
>
> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
>
>> Personally, I've got mixed feelings about wikis from experience with
>> previous projects, since they get out of date very rapidly indeed. They
>> do work well if someone's maintaining it, but if that's the case, why
>> not just push these tips and guides to the existing ocaml.org site?
>>
>> I'm happy to run a wiki on the OCL infrastructure, but would strongly
>> prefer contributions to the ocaml.org Git repo with all this good stuff
>> instead!  If it really turns out we need a swanky wiki, that can be arranged
>> later...
>
> Why not use the wiki provided by Github for the ocaml.org project?
>
>> -anil
>
> Benedikt

The Github wiki could be used as an easy access staging area for
information before it is moved into the main site.  It is easier to
edit a wiki than it is to checkout a git repository, edit content and
submit your changes.  If the wiki is treated as an area for
proposed/in progress material for ocaml.org then it could be useful
for more casual contributors.

Hez

Re: [Caml-list] OCaml wiki

[Wojciech Meyer]

Hi Ashish,

On Fri, Dec 21, 2012 at 2:49 AM, Ashish Agarwal <agarwal1975@gmail.com> wrote:
> A wiki could be good but I strongly encourage any such effort to integrate
> with ocaml.org, and to carefully weigh the pros and cons. Wikis make
> contributions easier, but you need someone to keep the content organized and
> do some basic quality control. Also, the structure of the documentation is
> not very customizable. The question is whether pushing to a git repo (the
> current contribution method for ocaml.org) is so much harder (given that
> we're all programmers after all).

yes, the intention is always go integrate with ocaml.org. Maybe we can
sort out the problem of submitting changes programaticaly, i.e. repo
with tools that simplify the whole process.
The bottleneck I see that the changes needs to be "formally approved"
- the git repo merged, where it takes a bit more time and shifts the
responsibiltiy to another person.
I can see advantage of that but then doing small changes is more difficult.

>
> The tutorials page is a good candidate for converting to wiki format, but
> remember that a wiki is where all this content came from, and it eventually
> got out of date. We could create wiki.ocaml.org, but then the question is
> how to make it integrate nicely with the rest of the pages that don't fit
> the wiki model.

the same theme and nice search box would be enough?

>
> Finally, which wiki software to use? None are very good, and who amongst us
> is keen to hack into php code. My initial goal for ocaml.org was to use
> ocsigen and ocsimore, but there is a big upfront cost in getting such a site
> implemented.

My answer would be as lightweight as possible, oddmuse is perl,
mediawiki is php.
Also these are wiki engines, so we probably don't need to hack on it.
They are fairly robust too.
So no need to worry that we need to get dirty with php :)
I also think ocsigen with ocsimore would be cool to have at some
point, it's a big deal for any language to have self hosting webserver
with dynamic pages.

>
> Whatever the community decides, we can support and integrate with ocaml.org.
> My only strong opinion is please don't build a separate unrelated site, with
> duplication of effort and and fragmentation of content.

We could have at least a static webpage generator like Stog, and keep
the content in the markup that can be pushed to ocaml.org.
It would be then easier to write any content and diff it.

Thanks,
-Wojciech

Re: [Caml-list] OCaml wiki

[Adrien]

On 21/12/2012, Wojciech Meyer <wojciech.meyer@gmail.com> wrote:
> Hi Ashish,
>
> On Fri, Dec 21, 2012 at 2:49 AM, Ashish Agarwal <agarwal1975@gmail.com>
> wrote:
>>
>> Finally, which wiki software to use? None are very good, and who amongst
>> us
>> is keen to hack into php code. My initial goal for ocaml.org was to use
>> ocsigen and ocsimore, but there is a big upfront cost in getting such a
>> site
>> implemented.
>
> My answer would be as lightweight as possible, oddmuse is perl,
> mediawiki is php.
> Also these are wiki engines, so we probably don't need to hack on it.
> They are fairly robust too.
> So no need to worry that we need to get dirty with php :)
> I also think ocsigen with ocsimore would be cool to have at some
> point, it's a big deal for any language to have self hosting webserver
> with dynamic pages.
>

Dokuwiki is *much* simpler than mediawiki and works well.

-- 
Adrien Nader

Re: [Caml-list] OCaml search into libraries for ocaml.org

[Leo White]

>For the record, I plan to extend Argot to be able to merge the data
>produced by different runs. You can see how Argot works on the
>standard library at the following address:
>	http://argot.x9c.fr/distrib/argot-4.00-libref-frame/argot_index.html
>
>Currently the information is dumped as JavaScript calls to functions
>allowing to populate data structures. Now, one of the question is
>about the output format(s). From the top of my head:
>  - json / xml, acting as lingua franca linking with other tools;
>  - OCaml marshal format, enabling easy use from OCaml programs;
>  - SQL insert commands, allowing to populate a database.
>
>I would be glad to get advice on this question, and also
>possible feature requests about Argot, whose homepage is:
>	http://argot.x9c.fr
>

I am currently working on updating the front-end of ocamldoc, so that it 
can output the inline documentation into a ".cmd" file, to accompany the 
new ".cmt" files.

We hope to use this for generating the documentation for docs.ocaml.org, as 
well as for generating local documentation for packages installed with 
OPAM.

If Argot dumped its data in OCaml marshall format then it would be easy to 
create OCaml tools that searched through collections of .cmd/.cmt files.

Regards,

Leo

Re: [Caml-list] OCaml wiki

[Siraaj Khandkar]

+1

Wiki is a fun concept, but is a complete mess in practice.

It has some versioning capabilities, but not nearly as sophisticated as a DVCS
such as Git. Obviously, there're editing capabilities, but not nearly as
productive as your favorite text editor.

Why force suboptimal tools on people that are interested in an optimal
programming language? ;)

Now, what about the maintainers? How do they even begin to keep track of tiny
edits to 1000's of wiki pages? Queueing theory to the rescue! A pull request
queue gives them a chance to audit the contributions in a sane manner (without
wasting their volunteered time).


On Dec 20, 2012, at 9:49 PM, Ashish Agarwal <agarwal1975@gmail.com> wrote:

> A wiki could be good but I strongly encourage any such effort to integrate
> with ocaml.org, and to carefully weigh the pros and cons. Wikis make
> contributions easier, but you need someone to keep the content organized
> and do some basic quality control. Also, the structure of the documentation
> is not very customizable. The question is whether pushing to a git repo
> (the current contribution method for ocaml.org) is so much harder (given
> that we're all programmers after all).
> 
> The tutorials page is a good candidate for converting to wiki format, but
> remember that a wiki is where all this content came from, and it eventually
> got out of date. We could create wiki.ocaml.org, but then the question is
> how to make it integrate nicely with the rest of the pages that don't fit
> the wiki model.
> 
> Finally, which wiki software to use? None are very good, and who amongst us
> is keen to hack into php code. My initial goal for ocaml.org was to use
> ocsigen and ocsimore, but there is a big upfront cost in getting such a
> site implemented.
> 
> Whatever the community decides, we can support and integrate with ocaml.org.
> My only strong opinion is please don't build a separate unrelated site,
> with duplication of effort and and fragmentation of content.
> 
> 
> On Thu, Dec 20, 2012 at 6:50 PM, Wojciech Meyer <wojciech.meyer@gmail.com>wrote:
> 
>> Anil Madhavapeddy <anil@recoil.org> writes:
>> 
>>> On 20 Dec 2012, at 23:31, Benedikt Meurer <
>> benedikt.meurer@googlemail.com> wrote:
>>>> 
>>>> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
>>>> 
>>>>> Personally, I've got mixed feelings about wikis from experience with
>>>>> previous projects, since they get out of date very rapidly indeed. They
>>>>> do work well if someone's maintaining it, but if that's the case, why
>>>>> not just push these tips and guides to the existing ocaml.org site?
>>>>> 
>>>>> I'm happy to run a wiki on the OCL infrastructure, but would strongly
>>>>> prefer contributions to the ocaml.org Git repo with all this good
>> stuff
>>>>> instead!  If it really turns out we need a swanky wiki, that can be
>> arranged
>>>>> later...
>>>> 
>>>> Why not use the wiki provided by Github for the ocaml.org project?
>>> 
>>> That works too; Thomas has written a Github Markdown to HTML converter in
>>> COW [1], and is using that to generate the OPAM website from the Github
>>> wiki (for the documentation that you see on opam.ocamlpro.com).
>> 
>> Yes, we could use github pages as long as they are searchable, I see no
>> problem with it. I think the biggest advantage of wiki would be that
>> everything would be in single place and hyperlinked.
>> 
>> As for protecting the wiki from being up-date emacswiki [1] is always a
>> great example that it is possible as long as people maintain their
>> webpages. Also, I feel that ocaml.org pages on github would be a good
>> entry point.
>> 
>> [1] http://emacswiki.org/
>> 
>> -Wojciech

-- 
Siraaj Khandkar
.o.
..o
ooo

Re: [Caml-list] OCaml wiki

[Vincent Balat]

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

Hi,

We have been using our home-made (Eliom based) wiki for years on 
http://ocsigen.org and http://www.pps.univ-paris-diderot.fr and it is probably 
a good candidate for ocaml.org. The project is called Ocsimore (see 
http://ocsigen.org/ocsimore ).

You can test it on page:
https://ocsigen.org/sandboxwiki/

Log in with user "test", password "test".

and see the manual for the syntax here: 
https://ocsigen.org/ocsimore/dev/manual/wiki

This wiki is somewhat different from all others, but has very interesting 
features that may be useful for ocaml.org:

 * you can mix static pages and wiki pages: if the static page is present, it 
will be sent, otherwise the wiki page is displayed. It is possible for example 
to keep the current web site and add progressively new pages using the wiki.

 * you can create several wikis on the website, corresponding to different 
rights. For example http://ocsigen.org/devarea/ is a wiki restricted to 
ocsigen's developers.

 * There is no default page container, and no default stylesheet: each wiki 
has its own container, common to every page of the wiki, that is itself 
written using wiki syntax. Editing the container requires special rights.

 * CSS are also edited online (by the users who have the right for this)

 * You can create CSS for the whole wiki or specific CSS for some pages

 * The base component of the wiki is not the page, but the "wikibox"
Each page (and each wikibox) can contain several wikiboxes, and a wikibox may 
appear on several pages

 * Each wikibox can be given specific rights (read/write/see history/change 
CSS...)

 * Each wikibox may itself be a container. For example if you want a menu 
common to several pages.

 * The wiki syntax is following the wikicreole standard, with some additions. 
The goal is to have most the possibilities offered by HTML. All the pages from 
the websites mentioned above are written with this syntax.

 * It is possible to write extensions to the wiki syntax. For exemple we have
<<code language="ocaml"| ... >> to display OCaml with syntax highlighting.


Ocsimore also has a forum module (for messages/comments) but it is still beta.

Ocsimore is conceived to be extensible and very customisable (even if it 
requires to understand a complex piece of code). It has very powerful right 
managements.

We never announced/released Ocsimore yet because there are still a lot of work 
to do to improve user friendliness. But things improved a lot in the past 
months and OCaml developers (and ocaml.org admins) can probably cope with it).
We will release version 1 soon.

Vincent [for the Ocsigen team]


> Hi,
> 
> These days ocaml.org is a great resource and starting point for the
> community and people interested in learning OCaml. It would be great
> however if we have a collective wiki for OCaml too. Not being here at
> any rate competitive and just complementary.
> 
> It could cover:
> - using core toolchain
> - tooling like Oasis, OPAM, ocamlfind, ocamlbuild etc.
> - type system tricks
> - small projects with good code examples
> - tools settings, emacs & vim configuration snippets
> etc.
> 
> it should be searchable, and fairly centralised.
> 
> What kind of wiki engine we would like to use?
> 
> I'd just opt either for oddmuse, mediawiki perhaps with some movement
> towards custom one based on Ocsigen and Eliom, but here I don't have any
> strong opinions, feel free to propose anything else.
> 
> Separate issue is storage and server etc., I'd happily organise/discuss
> these things, once we know the details :-)
> 
> I'm open for any ideas and people joining up with the effort.
> 
> Thanks,
> 
> -Wojciech

[-- Attachment #2: Type: text/html, Size: 15420 bytes --]

Re: [Caml-list] OCaml wiki

[Ashish Agarwal]

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

On Fri, Dec 21, 2012 at 8:05 AM, Wojciech Meyer <wojciech.meyer@gmail.com>wrote:

The bottleneck I see that the changes needs to be "formally approved"
>

This is currently required because the ocaml.org repo contains code, which
is run hourly on a server (formerly at OCamlPro, now at NYU, soon at OCaml
Labs). Giving too many people direct push permission would be a security
risk. Nonetheless, this can easily be resolved. We can have a separate repo
for pure text contributions, and the ocaml.org code could pull from that
one at publish time.


My answer would be as lightweight as possible, oddmuse is perl, mediawiki
> is php.
>

I'd go even lighter. So far the idea I like best is using github. We could
create a new repo ocaml.org-wiki, in which we use just the wiki feature.
This provides pure text files which can be manipulated to generate nice
output however we want. We can give push permission to everyone who
requests it.

Before committing to this, I'd like to know if something like 99 Problems
(solved) in OCaml <http://ocaml.org/tutorials/99problems.html> could be
supportable in a wiki (not just in theory, but realistically what work does
it take)? Note it has images, icons to indicate the difficulty level, code
that is auto-run through OCaml's toploop library, clickable boxes that
show/hide the solution, and an auto-generated table of contents. All of
these little details add up to making the page nice. A plain text version
of this would be lame. Ideally, the tutorials, which are currently plain
text, could also include more rich content like this.



> Also these are wiki engines, so we probably don't need to hack on it.
>

Various hacking ends up being required. If you want to style the wiki
content, you might have to change the attributes on the html elements, or
something. Maybe someday we want to ocaml.org to have user accounts for
some other reason, and at that point it would be nice to make the wiki
login system integrate with these other services. Maybe the wiki has an SSO
capability that works perfectly, but maybe you end up having to read php
code.


So no need to worry that we need to get dirty with php :)
>

It does scare me!



> I also think ocsigen with ocsimore would be cool to have at some point


I'm enticed by this a lot! The trick is to start this on some sub-component
of the website without disrupting the current work flow. Pick a particular
feature that would benefit from the rich dynamic capabilities ocsigen
enables, implement that in a separate repo, show the code works, is
maintainable, and then it can be integrated into ocaml.org.


We could have at least a static webpage generator like Stog
>

That's what we have, but we are using Christophe Troestler's Weberizer.

We should keep in mind all of the above is asking a lot from various
people. Having an ocsigen backend means we are asking OCaml Labs to provide
a server with ocsigen installed. Using the github wiki syntax to html
converter, or weberizer, or stog means asking their respective authors to
do work when the tools don't do exactly what is needed. Converting the
current tutorials to wiki syntax will take hours, after hours were already
spent converting them into html. But hey... a little peer pressure to get a
better website is worth it.  :)

[-- Attachment #2: Type: text/html, Size: 4725 bytes --]

Re: [Caml-list] OCaml wiki

[Ashish Agarwal]

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

On Fri, Dec 21, 2012 at 11:20 AM, Vincent Balat <
vincent.balat@univ-paris-diderot.fr> wrote:


> It is possible for example to keep the current web site and add
> progressively new pages using the wiki.
>

Nice! If we did this, a gradual transition is key.



> We will release version 1 soon.
>

This is even more critical. Currently the ocsimore page says "It is under
development (not usable for now)." Using a wiki locks us in to a very
specific model. We need confidence the tool is stable and will continue to
be maintained and developed.




> > Hi,
>
> >
>
> > These days ocaml.org is a great resource and starting point for the
>
> > community and people interested in learning OCaml. It would be great
>
> > however if we have a collective wiki for OCaml too. Not being here at
>
> > any rate competitive and just complementary.
>
> >
>
> > It could cover:
>
> > - using core toolchain
>
> > - tooling like Oasis, OPAM, ocamlfind, ocamlbuild etc.
>
> > - type system tricks
>
> > - small projects with good code examples
>
> > - tools settings, emacs & vim configuration snippets
>
> > etc.
>
> >
>
> > it should be searchable, and fairly centralised.
>
> >
>
> > What kind of wiki engine we would like to use?
>
> >
>
> > I'd just opt either for oddmuse, mediawiki perhaps with some movement
>
> > towards custom one based on Ocsigen and Eliom, but here I don't have any
>
> > strong opinions, feel free to propose anything else.
>
> >
>
> > Separate issue is storage and server etc., I'd happily organise/discuss
>
> > these things, once we know the details :-)
>
> >
>
> > I'm open for any ideas and people joining up with the effort.
>
> >
>
> > Thanks,
>
> >
>
> > -Wojciech
>
>
>

[-- Attachment #2: Type: text/html, Size: 6130 bytes --]

Re: [Caml-list] OCaml wiki

[Siraaj Khandkar]

Or, it seems one can haz cake and eat it too! :)

https://github.com/jgm/gitit


On Dec 21, 2012, at 10:33 AM, Siraaj Khandkar <siraaj@khandkar.net> wrote:

> +1
> 
> Wiki is a fun concept, but is a complete mess in practice.
> 
> It has some versioning capabilities, but not nearly as sophisticated as a DVCS
> such as Git. Obviously, there're editing capabilities, but not nearly as
> productive as your favorite text editor.
> 
> Why force suboptimal tools on people that are interested in an optimal
> programming language? ;)
> 
> Now, what about the maintainers? How do they even begin to keep track of tiny
> edits to 1000's of wiki pages? Queueing theory to the rescue! A pull request
> queue gives them a chance to audit the contributions in a sane manner (without
> wasting their volunteered time).
> 
> 
> On Dec 20, 2012, at 9:49 PM, Ashish Agarwal <agarwal1975@gmail.com> wrote:
> 
>> A wiki could be good but I strongly encourage any such effort to integrate
>> with ocaml.org, and to carefully weigh the pros and cons. Wikis make
>> contributions easier, but you need someone to keep the content organized
>> and do some basic quality control. Also, the structure of the documentation
>> is not very customizable. The question is whether pushing to a git repo
>> (the current contribution method for ocaml.org) is so much harder (given
>> that we're all programmers after all).
>> 
>> The tutorials page is a good candidate for converting to wiki format, but
>> remember that a wiki is where all this content came from, and it eventually
>> got out of date. We could create wiki.ocaml.org, but then the question is
>> how to make it integrate nicely with the rest of the pages that don't fit
>> the wiki model.
>> 
>> Finally, which wiki software to use? None are very good, and who amongst us
>> is keen to hack into php code. My initial goal for ocaml.org was to use
>> ocsigen and ocsimore, but there is a big upfront cost in getting such a
>> site implemented.
>> 
>> Whatever the community decides, we can support and integrate with ocaml.org.
>> My only strong opinion is please don't build a separate unrelated site,
>> with duplication of effort and and fragmentation of content.
>> 
>> 
>> On Thu, Dec 20, 2012 at 6:50 PM, Wojciech Meyer <wojciech.meyer@gmail.com>wrote:
>> 
>>> Anil Madhavapeddy <anil@recoil.org> writes:
>>> 
>>>> On 20 Dec 2012, at 23:31, Benedikt Meurer <
>>> benedikt.meurer@googlemail.com> wrote:
>>>>> 
>>>>> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
>>>>> 
>>>>>> Personally, I've got mixed feelings about wikis from experience with
>>>>>> previous projects, since they get out of date very rapidly indeed. They
>>>>>> do work well if someone's maintaining it, but if that's the case, why
>>>>>> not just push these tips and guides to the existing ocaml.org site?
>>>>>> 
>>>>>> I'm happy to run a wiki on the OCL infrastructure, but would strongly
>>>>>> prefer contributions to the ocaml.org Git repo with all this good
>>> stuff
>>>>>> instead!  If it really turns out we need a swanky wiki, that can be
>>> arranged
>>>>>> later...
>>>>> 
>>>>> Why not use the wiki provided by Github for the ocaml.org project?
>>>> 
>>>> That works too; Thomas has written a Github Markdown to HTML converter in
>>>> COW [1], and is using that to generate the OPAM website from the Github
>>>> wiki (for the documentation that you see on opam.ocamlpro.com).
>>> 
>>> Yes, we could use github pages as long as they are searchable, I see no
>>> problem with it. I think the biggest advantage of wiki would be that
>>> everything would be in single place and hyperlinked.
>>> 
>>> As for protecting the wiki from being up-date emacswiki [1] is always a
>>> great example that it is possible as long as people maintain their
>>> webpages. Also, I feel that ocaml.org pages on github would be a good
>>> entry point.
>>> 
>>> [1] http://emacswiki.org/
>>> 
>>> -Wojciech

-- 
Siraaj Khandkar
.o.
..o
ooo

AW: [Caml-list] OCaml search into libraries for ocaml.org

[Gerd Stolpmann]

Am 21.12.2012 02:31:54 schrieb(en) Francois Berenger:
> Hello,
> 
> About ocaml.org: Wojciech Meyer just asked for a Wiki.
> 
> In addition to this, as a programmer, I am especially interested
> into being able to search into OCaml libraries via a search engine.
> 
> A simple engine as in the left of this page:
> http://projects.camlcity.org/projects/ocamlnet.html
> is already useful.

It's not simple, btw. This engine bases on a syntactical analysis of  
Ocaml sources, and that makes it possible to search e.g. for type names.

> However, I'd like the search engine to be able to
> do search by type queries, "a la" Hoogle and as in:
> http://search.ocaml.jp/

No, it cannot do this. That's because it doesn't use compiled sources  
as basis. When I developed this page, that was simply not the first  
priority, I also wanted to make sources searchable that cannot be  
built, or that are just examples.

Now that the compiler can dump the type expressions, it is possible to  
add such a search (so far there is an encoding for a full-text search  
engine).

> But it should index more libraries. For example, all
> packages available in OPAM.

Sorry, as GODI inventor I'm the wrong address here. I have plans to add  
OASIS packages (very soon), but I won't support another format.

Gerd

> Regards,
> F.
> 
> 
>-- 
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
> 
-- 
------------------------------------------------------------
Gerd Stolpmann, Darmstadt, Germany    gerd@gerd-stolpmann.de
Creator of GODI and camlcity.org.
Contact details:        http://www.camlcity.org/contact.html
Company homepage:       http://www.gerd-stolpmann.de
------------------------------------------------------------

Re: AW: [Caml-list] OCaml search into libraries for ocaml.org

[Török Edwin]

On 12/21/2012 09:57 PM, Gerd Stolpmann wrote:
> Am 21.12.2012 02:31:54 schrieb(en) Francois Berenger:

>> However, I'd like the search engine to be able to
>> do search by type queries, "a la" Hoogle and as in:
>> http://search.ocaml.jp/
> 
> No, it cannot do this. That's because it doesn't use compiled sources as basis. When I developed this page, that was simply not the first priority, I also wanted to make sources searchable that cannot
> be built, or that are just examples.
> 
> Now that the compiler can dump the type expressions, it is possible to add such a search (so far there is an encoding for a full-text search engine).
> 
>> But it should index more libraries. For example, all
>> packages available in OPAM.
> 
> Sorry, as GODI inventor I'm the wrong address here. I have plans to add OASIS packages (very soon), but I won't support another format.

How about supporting type search for all packages in GODI then?
search.ocaml.jp only supports stdlib and extlib, supporting search among all GODI packages would certainly be an improvement.

Best regards,
--Edwin

AW: AW: [Caml-list] OCaml search into libraries for ocaml.org

[Gerd Stolpmann]

Am 21.12.2012 21:22:53 schrieb(en) Török Edwin:
> On 12/21/2012 09:57 PM, Gerd Stolpmann wrote:
> > Am 21.12.2012 02:31:54 schrieb(en) Francois Berenger:
> 
> >> However, I'd like the search engine to be able to
> >> do search by type queries, "a la" Hoogle and as in:
> >> http://search.ocaml.jp/
> >
> > No, it cannot do this. That's because it doesn't use compiled  
> sources as basis. When I developed this page, that was simply not the  
> first priority, I also wanted to make sources searchable that cannot
> > be built, or that are just examples.
> >
> > Now that the compiler can dump the type expressions, it is possible  
> to add such a search (so far there is an encoding for a full-text  
> search engine).
> >
> >> But it should index more libraries. For example, all
> >> packages available in OPAM.
> >
> > Sorry, as GODI inventor I'm the wrong address here. I have plans to  
> add OASIS packages (very soon), but I won't support another format.
> 
> How about supporting type search for all packages in GODI then?
> search.ocaml.jp only supports stdlib and extlib, supporting search  
> among all GODI packages would certainly be an improvement.

Yes. I just need to figure out how to smuggle -bin-annot into all  
builds. The rest seems to be a relatively moderate extension of the  
existing code. Maybe when Xmas gets too boring...

Gerd

> Best regards,
> --Edwin
> 
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
> 
> 

-- 
------------------------------------------------------------
Gerd Stolpmann, Darmstadt, Germany    gerd@gerd-stolpmann.de
Creator of GODI and camlcity.org.
Contact details:        http://www.camlcity.org/contact.html
Company homepage:       http://www.gerd-stolpmann.de
------------------------------------------------------------

Re: AW: AW: [Caml-list] OCaml search into libraries for ocaml.org

[Edgar Friendly]

On 12/21/2012 3:34 PM, Gerd Stolpmann wrote:
> Yes. I just need to figure out how to smuggle -bin-annot into all 
> builds. The rest seems to be a relatively moderate extension of the 
> existing code. Maybe when Xmas gets too boring...
>
As a library author, should I install .cmt files for all my modules?  
Should we make this the default in oasis?

E.

AW: AW: AW: [Caml-list] OCaml search into libraries for ocaml.org

[Gerd Stolpmann]

Am 21.12.2012 21:37:02 schrieb(en) Edgar Friendly:
> On 12/21/2012 3:34 PM, Gerd Stolpmann wrote:
>> Yes. I just need to figure out how to smuggle -bin-annot into all  
>> builds. The rest seems to be a relatively moderate extension of the  
>> existing code. Maybe when Xmas gets too boring...
>> 
> As a library author, should I install .cmt files for all my modules?   
> Should we make this the default in oasis?

I guess wrappers for all the ocaml* commands would be enough. Or maybe  
a patch for ocaml. It would be painful if we had to change all the  
existing builds.

Gerd

> E.
> 
>-- 
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
> 


-- 
------------------------------------------------------------
Gerd Stolpmann, Darmstadt, Germany    gerd@gerd-stolpmann.de
Creator of GODI and camlcity.org.
Contact details:        http://www.camlcity.org/contact.html
Company homepage:       http://www.gerd-stolpmann.de
------------------------------------------------------------

Library install standards (was: Re: AW: AW: AW: [Caml-list] OCaml search into libraries for ocaml.org)

[Edgar Friendly]

On 12/21/2012 3:41 PM, Gerd Stolpmann wrote:
> Am 21.12.2012 21:37:02 schrieb(en) Edgar Friendly:
>> As a library author, should I install .cmt files for all my modules?  
>> Should we make this the default in oasis?
>
> I guess wrappers for all the ocaml* commands would be enough. Or maybe 
> a patch for ocaml. It would be painful if we had to change all the 
> existing builds.
Wrapping the ocaml* commands seems reasonable, but I was asking a more 
general question about what files should be installed for libraries.

1) .cma and .cmxa files clearly need to be installed for linking
2) .cmi files need to be installed for compiling (?)
3) .cmx files should be installed for cross-module inlining / optimization
4) .cmt files for compiler tools
5) .mli files for users to read directly (optional)
6) Any .cmo files not put into .cma libraries
What am I forgetting?

E.

[Caml-list] Re: Library install standards

[Török Edwin]

On 12/21/2012 10:48 PM, Edgar Friendly wrote:
> On 12/21/2012 3:41 PM, Gerd Stolpmann wrote:
>> Am 21.12.2012 21:37:02 schrieb(en) Edgar Friendly:
>>> As a library author, should I install .cmt files for all my modules?  Should we make this the default in oasis?
>>
>> I guess wrappers for all the ocaml* commands would be enough. Or maybe a patch for ocaml. It would be painful if we had to change all the existing builds.
> Wrapping the ocaml* commands seems reasonable, but I was asking a more general question about what files should be installed for libraries.
> 
> 1) .cma and .cmxa files clearly need to be installed for linking

.a and .so too.

> 2) .cmi files need to be installed for compiling (?)
> 3) .cmx files should be installed for cross-module inlining / optimization

are .cmx files needed when .cmxa is available?

> 4) .cmt files for compiler tools
> 5) .mli files for users to read directly (optional)
> 6) Any .cmo files not put into .cma libraries
> What am I forgetting?

.cmxs, but oasis handles that already.
And of course a META file, but thats implied.

Best regards,
--Edwin

AW: [Caml-list] Re: Library install standards

[Gerd Stolpmann]

Am 21.12.2012 21:59:59 schrieb(en) Török Edwin:
> On 12/21/2012 10:48 PM, Edgar Friendly wrote:
> > On 12/21/2012 3:41 PM, Gerd Stolpmann wrote:
> >> Am 21.12.2012 21:37:02 schrieb(en) Edgar Friendly:
> >>> As a library author, should I install .cmt files for all my  
> modules?  Should we make this the default in oasis?
> >>
> >> I guess wrappers for all the ocaml* commands would be enough. Or  
> maybe a patch for ocaml. It would be painful if we had to change all  
> the existing builds.
> > Wrapping the ocaml* commands seems reasonable, but I was asking a  
> more general question about what files should be installed for  
> libraries.
> >
> > 1) .cma and .cmxa files clearly need to be installed for linking
> 
> .a and .so too.
> 
> > 2) .cmi files need to be installed for compiling (?)
> > 3) .cmx files should be installed for cross-module inlining /  
> optimization
> 
> are .cmx files needed when .cmxa is available?

No, they aren't. However, the presence of .cmx files enables  
cross-module inlining, so at least for select modules it is reasonable  
to install them.

> > 4) .cmt files for compiler tools
> > 5) .mli files for users to read directly (optional)
> > 6) Any .cmo files not put into .cma libraries
> > What am I forgetting?
> 
> .cmxs, but oasis handles that already.
> And of course a META file, but thats implied.

IMHO, the question of compiler switches is also important. I recommend  
to build all modules with -g, because this enables debugging.

For some libraries I also install .p.cmxa, i.e. the same library  
compiled with -p for profiling. I don't know how to do that with oasis,  
though.

Gerd

> 
> Best regards,
> --Edwin
> 
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
> 
> 



-- 
------------------------------------------------------------
Gerd Stolpmann, Darmstadt, Germany    gerd@gerd-stolpmann.de
Creator of GODI and camlcity.org.
Contact details:        http://www.camlcity.org/contact.html
Company homepage:       http://www.gerd-stolpmann.de
------------------------------------------------------------

Re: [Caml-list] OCaml wiki

[Vincent Balat]

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

> > It is possible for example to keep the current web site and add
> > progressively new pages using the wiki.
> 
> Nice! If we did this, a gradual transition is key.
> 
> > We will release version 1 soon.
> 
> This is even more critical. Currently the ocsimore page says "It is under
> development (not usable for now)." Using a wiki locks us in to a very
> specific model. We need confidence the tool is stable and will continue to
> be maintained and developed.

I can change this sentence if it scares you ;) Actually Ocsimore has been used 
for years at PPS without any problem. Every member of the laboratory has its 
own wiki for his personal pages and people like it. 
The part that is still not really user friendly is the administration 
interface. But a lot of work has been done in the past few months by the new 
maintainer Jacques-Pascal Deplaix and he plans to improve a few more things 
during the next weeks. I just don't want to call 1.0 something that is too 
difficult to install or that is badly documented.

I understand that you would prefer a wiki that is used on more than 2 Web 
sites, and that has commercial suport (or at least a large community) and I 
won't blame you for doing that choice. But Ocsimore is not going to die 
(because it's part of the Ocsigen project). And using Ocsimore on ocaml.org 
would be a good opportunity to support an OCaml project (may be OCaml Labs or 
the consortium could help if you need new features?). It would also be easier 
to find contributors amongst OCaml developers for creating customized 
extensions you may need ...

Why not giving it a try? We can install and configure it if you want.

Vincent

[-- Attachment #2: Type: text/html, Size: 5063 bytes --]

Re: [Caml-list] OCaml wiki

[Ashish Agarwal]

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

On Sun, Dec 23, 2012 at 9:53 AM, Vincent Balat <
vincent.balat@univ-paris-diderot.fr> wrote:

I just don't want to call 1.0 something that is too difficult to install or
> that is badly documented.
>

That's a good policy.

Why not giving it a try? We can install and configure it if you want.
>

I'd like to test it out, but the issue is of course time. We currently have
37 open issues [1] on the ocaml.org repo, and that doesn't include any of
the requests made over the last few days on this list. Those items need to
take priority before we start investigating new implementation
technologies. But if you can configure an installation for us, that'll be a
nice start. More people-hours will be a big help!

[1] https://github.com/ocaml/ocaml.org/issues?state=open

[-- Attachment #2: Type: text/html, Size: 1775 bytes --]