In the case of method/symbol documentation that is indeed correct and no
markup language is my first port of call for that. The first pass was done
with clang which is pretty good thus far - .eo is going to be much more
help once the interfaces become more commonly used.
However what your email misses is all the other documentation that we are
hoping to reference - the helpful context documents (mainloop / alpha
blending) and examples or walkthroughs that would make a much better hand
holding experience. Like I said before this is intending to help folk get
started with EFL - the steep learning curve is due to much more than method
parameter order and bounds.
Thanks,
Andy
On Tue, 31 Oct 2017 at 07:36 Carsten Haitzler <ras...@rasterman.com> wrote:
> On Tue, 24 Oct 2017 13:39:14 +0000 Andrew Williams <a...@andywilliams.me>
> said:
>
> > On Tue, 24 Oct 2017 at 13:09 Carsten Haitzler <ras...@rasterman.com>
> wrote:
> >
> > > On Mon, 23 Oct 2017 11:57:56 +0000 Andrew Williams <
> a...@andywilliams.me>
> > > said:
> > >
> > > > Hi,
> > > >
> > > > I will try to provide as much insight as I can:
> > > >
> > > > As many of the community are aware I started the Edi project to help
> get
> > > > people into coding on EFL - the learning curve is very steep and the
> > > > tooling was basically commandline based. Documentation is a big part
> of
> > > the
> > > > solution and we've come a long way both with the wiki and with the
> .eo
> > > > format for defining functionality. However this is set up to deliver
> only
> > > > on our website which a) is online and b) is external to the IDE.
> > > > To make a more integrated experience I started to think about how the
> > > > documentation could be more portable - so that it could be rendered
> in
> > > Edi
> > > > or other documentation browser online or offline, in the workflow of
> > > > someone's coding. Dokuwiki is a challenge here as the only renderer
> is
> > > the
> > > > dokuwiki web ui so reading the files off the filesystem is not
> really a
> > > > possibility without coding up a new render implementation.
> > >
> > > i was actually thinking of the docs always being online... :) then
> changes
> > > and
> > > improvements are immediately accessible to all users/devs ... :) yes
> yes.
> > > hard
> > > to refer to docs while on a plane ... i know. :)
> > >
> >
> > In it's current form not only do you have to be online you have to have a
> > browser window open alongside your code. To be worried about immediate
> > propagation of improvements implies a lot more documentation activity
> than
> > we see - and once the API has a solid release would important changes to
> > them not be less common?
> >
> > > A few conversations later and I was chatting to Cedric about what we
> can
> > > do
> > > > to make the documentation cleaner and he mentioned that Samsung was
> also
> > > > interested in this - and that they may be willing to finance some
> > > technical
> > > > writers to help. So he managed to get some professionals signed up
> and
> > > now
> > > > have people raring to go with documentation - but they don't know
> > > dokuwiki
> > > > and honestly I don't think that spending all day editing text files
> in a
> > > > browser window is the best way to write reams of documentation. A
> markup
> > > > format with external editors would mean higher productivity and also
> > > > increased portability.
> > > >
> > > > And so here we are. It looks like Markdown is a format that provides
> a
> > > lot
> > > > of additional benefits in terms of contributors, portability and
> future
> > > > proofing.
> > >
> > > ok. so here's a question. edi. how do you plan to display docs in edi?
> > > going to
> > > write a madkrown parser/formatter in "c" and then use textblocks
> (entries,
> > > efl.ui.text) to display? nothing else exists at the moment. or
> planning to
> > > add
> > > "markdown handling" directly to efl.ui.text/textblock etc. (like
> markup is
> > > supported)? going to write an "exporter" that uses the wiki php cod to
> > > parse
> > > markdown but instead of html - generate textblock etc. markup?
> > >
> >
> > Ideally we would have a native markdown component for speed purpose - it
> > would make a nice editor as well as a way to view the docs and
> dynamically
> > link in context.
> > However that is a reasonable amount of work - due to the commonality of
> > this format we can get there faster by using a pre-built parser, hooking
> in
> > whatever clever linking we want and preview through something currently
> > available like HTML. Not the perfect solution but much quicker to get
> > working.
> >
> > > I hope that helps,
> > > > Andy
> > >
> > > --
> > > ------------- Codito, ergo sum - "I code, therefore I am"
> --------------
> > > Carsten Haitzler - ras...@rasterman.com
> >
> >
> > Not sure if that helps with the context you were looking for?
> > Andy
>
> more context.
>
> but if you want files for docs inside something like edi shouldn't they
> have far
> more semantic info -not markdown? like literally something like:
>
> class colors {
> property {
> name: color
> modes: RW
> type: int r (0-255), int g (0-255), int b (0-255), int a (0-255)
> description {
> "This is the premultiplied RGBA color with values fro 0 to 255 per"
> "component"
> }
> }
> func {
> name: clear
> description {
> "Clears the color from the target so no color is applied."
> }
> }
> }
>
> my point being edi would want a LOT more semantic info so it can do things
> like
> complain if a parameter is out of min/max bounds and so on... ? like edi
> really
> needs the eo file info etc. etc.
>
>
>
>
>
> --
> ------------- Codito, ergo sum - "I code, therefore I am" --------------
> Carsten Haitzler - ras...@rasterman.com
>
> --
http://andywilliams.me
http://ajwillia.ms
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
