On Wed, 01 Nov 2017 18:27:51 +0000 Andrew Williams <a...@andywilliams.me> said:
> Hi,
>
> Whatever rendering technologies we use within Edi is probably out of scope
> for this thread which was (in part) about using a more portable
> documentation format to allow folk to access the docs outwith the E website
> context.
> Markdown is working well for the documentation team as they can use their
> own editors before adding to the wiki for any final tweaks / links etc.
> I don't know about others but I think we're about out of reasons not to
> support this going forward.
well let's see. i still dislike us now having 2 markdown formats on our main
site.
> Thanks,
> Andy
>
> On Wed, 1 Nov 2017 at 00:53 Carsten Haitzler <ras...@rasterman.com> wrote:
>
> > On Tue, 31 Oct 2017 10:01:43 +0000 Andrew Williams <a...@andywilliams.me>
> > said:
> >
> > > Hi
> > >
> > > Ideally yes - but then images are part of the spec anyway - and tables
> > are
> > > pretty standard these days.
> >
> > ok. so then it'd have to be a mixed bag of textblocks/entries + tables or
> > boxes
> > containing them with tables done outside of these widgets. more involved to
> > create a display widget/layout at any rate.
> >
> > > Andy
> > >
> > > On Tue, 31 Oct 2017 at 08:37 Carsten Haitzler <ras...@rasterman.com>
> > wrote:
> > >
> > > > On Tue, 31 Oct 2017 08:18:37 +0000 Andrew Williams <
> > a...@andywilliams.me>
> > > > said:
> > > >
> > > > > 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.
> > > >
> > > > ok. i was just thinking reference
> > (struct/enum/func/method/property/class
> > > > info)
> > > > stuff. not things like tutorials and whatever. edi needing this
> > tutorial
> > > > land
> > > > stuff seems more fringe. reference docs - absolutely. i can see this.
> > like
> > > > tooltips and completion info as you type telling you about what you are
> > > > writing
> > > > and the limits/sage and so on.
> > > >
> > > > i mean... at a stretch i can see edi showing these docs, but then
> > doesn't
> > > > it
> > > > also have to handle inlined images (diagrams, screenshots and so on?).
> > > > tables,
> > > > and what not... right?
> > > >
> > > > > 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
> > > >
> > > >
> > > > --
> > > > ------------- Codito, ergo sum - "I code, therefore I am"
> > --------------
> > > > Carsten Haitzler - ras...@rasterman.com
> > > >
> > > > --
> > > http://andywilliams.me
> > > http://ajwillia.ms
> >
> >
> > --
> > ------------- 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
>
--
------------- Codito, ergo sum - "I code, therefore I am" --------------
Carsten Haitzler - ras...@rasterman.com
------------------------------------------------------------------------------
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
