On Wed, Apr 15, 2015, Carsten Haitzler wrote:
> On Wed, 15 Apr 2015 09:20:42 +0200 Adrien Nader <adr...@notk.org> said:
>
> > On Tue, Apr 14, 2015, Carsten Haitzler wrote:
> > > On Mon, 13 Apr 2015 21:27:49 +0200 Adrien Nader <adr...@notk.org> said:
> > >
> > > sorry - not addressing the below.. but i have now got a local dokuwiki
> > > patch
> > > that extends geshi (the code syntax hilighter) to teach it new keywords.
> > > the
> > > awesome bit - the keywords are just a text file in the wiki!
> > >
> > > http://www.enlightenment.org/ss/e-552cb0fa49e318.10726513.png
> > >
> > > see evas_object_del is hilighted. i have a file with:
> > >
> > > evas_object_del
> > > evas_object_show
> > > evas_object_hide
> > > eo_add
> > > eo_del
> > >
> > > and if any of these appear - they get linked... to the following url which
> > > is in an accompanying file:
> > >
> > > /docs/generated/c/keywords/{FNAMEL}
> > >
> > > so that means click on a link and it goes to:
> > >
> > > docs/generated/c/keywords/evas_object_del
> >
> > Do you plan on making "stable" ones? I don't think it's sane to link to
> > anything but the most recent stable release: lagging a bit for updates
> > is fine but linking to the devel stuff would be really bad imho.
>
> that would be the idea - these are all "latest stable release" - we rebuild
> link lists just around/before/after release (in the last week or so of freeze
> should be fine as no api should change). any new docs needed can be prepared
> FOR
> this period but not made live yet.
Sounds perfect to me. Must make sure to not lose previous ones so we can
show the previous versions too.
> > Also, what about an URI that is simpler to memorize? That's not
> > exclusive with the current one though. I'd really like to be able to
> > remember the URI to prepend to any function name in order to get its
> > doc: "docs/generated/c/keywords/" is a bit too long for that.
>
> google will end up finding stuff for you in the end. i would expect us to have
> an index page generated from that with just links or something. in fact just
> make the parent dir have key.txt and it can be the link list. bookmark that
> and
> go there when needed.
I don't know how different I am from the typical future visitors but I
like being to go hit the api references quickly.
People praise Qt's docs but for two slightly different search queries,
chances are you will get results from different versions of Qt, possibly
even from nokia days.
> > > on the site (www.e.org in front of course). this is the beginning of a
> > > namespace for docs. the above keywords markdown pages can be totally
> > > generated (and maybe even be master pages for these things) and it means
> > > code at least gets auto-linked. the symbol list is in the wiki so it can
> > > be
> > > extended by hand edits or auto-generation and commits to www-content git
> > > on
> > > the back-end without going through the wiki. something needs to
> > > collect/generate all these keywords (functions, enums, macros, typedef'ed
> > > types). in future for eo we can auto-generate them for classes, methods,
> > > events etc. etc. but it's a start.
> > >
> > > so to some extent by doing this dokuwiki mod, i'm answering the question
> > > partially to layout already a this mod relies on a flat layout of keywords
> > > (geshi relies on this for linking keywords - it doesnt understand context
> > > thus has to be flat). oh btw - geshi is the code syntax hilighter buried
> > > in
> > > dokuwiki (external project from dokuwiki though) and has hilighters for
> > > maybe 50+ languages (c, cpp, js, lua python are all there, even brainfuck
> > > and ruby!) :)
> >
> > That only applies to the API part, right?
>
> this is for generating links to keywords - ie reference. the same links will
> apply to any and ALL c code (you can have per language keyword lists).
Yes, ok.
> > > > Last year, Samsung contracted a company made of French borkers to
> > > > write its "native application" documentation, i.e. usage of EFLs on
> > > > Tizen. Last week, raster switched e.org to dokuwiki.
> > > > Well, I worked on that documentation and I really like dokuwiki so I
> > > > started porting the documentation.
> > > >
> > > > It was written as doxygen and we don't have any copyright on that;
> > > > however, the HTML output has been published as a mix of CC-BY 3.0, BSD
> > > > 3-clauses and LGPL v2.1 and Apache. It's not entirely consistent but in
> > > > any case, it's definitely usable (and probably with a better track of
> > > > licenses than what has existed until now).
> > >
> > > at the bottom of each page we can put a licence link and put a copy of the
> > > above licenses in our docs tree - we will comply happily then.
> >
> > Page per page or globally for the wiki?
>
> page per page that we import that is licensed like this. if we dont import it
> coming from elsewhere under a different license - we dont put it there.
Good.
> > > > Dokuwiki supports namespaces and we probably want to take advantage of
> > > > that; namespaces can appear in the URI either as "foo:bar" or "foo/bar"
> > > > and it's also possible to put a page directly at "foo".
> > > >
> > > > I think we could have namespaces and pages like:
> > > > doc/
> > > > doc/efl # lists and explains libraries
> > > > doc/efl/ecore/
> > > > doc/efl/ecore/events # covers events, their handling, the mainloop...
> > > > doc/efl/elementary/
> > > > doc/efl/elementary/concepts
> > > > doc/efl/elementary/widgets # nice, sorted, widget gallery
> > > > doc/efl/elementary/widgets/button # page-name is guessable from the API
> > > > doc/e17/
> > > > doc/e19/
> > >
> > > i agree on using the dir tree. as above - some of it i think we will
> > > auto-generate (someone runs a script when we do a release and populates
> > > git
> > > - they commit changes then to www-content). admittedly i'm talking
> > > "reference" docs vs howto/tutorials/concepts etc. - docs for a class, a
> > > func/method, a macro, a type, an enum etc. .. but these are a core part of
> > > docs. the tutorials need to link back to references so it's all
> > > integrated.
> > > maybe like:
> > >
> > > doc/ref/lib/efl/gen/c/key/KEYWORD # a specific keyword like
> > > "evas_object_del" doc/ref/lib/efl/gen/c/keyword-link.txt # link url for
> > > keywords for "c" land doc/ref/lib/efl/gen/c/keyword-list.txt # txt file
> > > with list of all keywords doc/lib/efl/start.txt # start page for efl in
> > > general (efl, elm etc.) ...
> > > doc/app/enlightenment/start.txt # start page for enlightenment as an app
> > > doc/app/edi/start.txt # start page for edi ... as an app
> > > ...
> > >
> > > (KEYWORD being evas_object_del or eo_del or evas_object_color_set or
> > > ecore_timer_add etc.). replace "c" with "cpp", "lua", "js" depending on
> > > language
> > >
> > > using gen/ to indicate some content there is generated - eg new "empty
> > > template" pages for new keywords - the keyword list page too is generated.
> > > (you can generate it by just listing the key dir above i guess).
> > > efl/start.txt can be where you start with efl and this is the first "i'm a
> > > noob" to efl specifically and this page can link/include further pages -
> > > eg
> > > getting started etc. from some other file (likely inside the efl/ dir).
> > > it's much like yours - but why bother namespace elm and ecore etc. - it's
> > > all efl - to people this is what matters. libs are separate
> >
> > There are plugins that generate namespace indexes ("nslist" for instance
> > I think).
> >
> > Agreed that we probably don't want to use namespaces for elm vs. ecore
> > vs. ...
> > It's fine for elm/ecore/eina/evas/edje but then you need to add
> > ephysics, emotion, eet, efreet and another dozen.
> >
> > What about a topical split maybe?
> > doc/efl/events
> > doc/efl/canvas
> > doc/efl/widgets
> > doc/efl/themes
> > doc/efl/networking
> > doc/efl/data-structures
> >
> > This list still smells of the underlying libs but it doesn't restrict us
> > in how we organize inside. It would also be possible to doc
> > doc/efl/gui/{canvas,widgets,themes} instead. This actually also quite
> > matches the topics in the tizen doc.
>
> yes. or something like this. this is tutorials and so on vs api reference
> which
> is different. for c at least we need no dirs as in c we have to live with a
> flat namespace anyway. :)
OK.
By the way, bindings are typically almost completely generated nowadays.
This means the API is the same besides a few minor tweaks. I believe it
makes little sense to have separate, per-language, documentation: a few
paragraphs should be enough to teach how to translate between the C API
and your preferred language.
> > > > Any thought? This really seems like the most blocking aspect to me.
> > > >
> > > > A few more things (most are for the wiki admins).
> > > >
> > > > What's missing or could be improved:
> > > > - the dokuwiki "syntax" page cannot be found on the wiki; it's a problem
> > > > because some dokuwiki plugins extend the syntax and it's difficult to
> > > > know which ones are enabled without that page
> > >
> > > just find any dokuwiki page - i actually use msot of what is supported in
> > > the example page on e.org (http://www.enlightenment.org/example)
> >
> > I'm most interested in support for syntax plugins. The dokuwiki syntax
> > page gets expanded by syntax plugins. You can see
> > http://win-builds.org/doku.php/wiki/syntax#syntax_plugins : it lists the
> > additional syntax that can be used on that very dokuwiki installation.
> >
> > I was wondering if I could use some mediawiki syntax for lists and
> > tables but without that page I couldn't tell.
>
> i can install it. i just kind of go "ugh" if i have to ALSO fix up css and
> styling too - it adds to the workload beyond just adding the plugin.
Ohhh, you don't like doing CSS? I can't understand why. :)
I think these plugins live entirely in the parsing part. They might add
some stuff to be able to nest blocks more than DW typically does but I'd
be surprised if that was the case and required changes.
> > > > - some filtering needs to be done: Tizen-specific stuff needs to be
> > > > stripped (there isn't much of it but you need to locate it)
> > > > - dokuwiki's table syntax is nice and simple but also too simple
> > >
> > > let's discuss this - as above. what do you need? we can add plugins as
> > > needed
> >
> > I searched a bit for plugins on dokuwiki's website and I think the
> > current ones that match the needs are:
> > https://www.dokuwiki.org/plugin:itemtable (tables)
> > https://www.dokuwiki.org/plugin:exttab3 (tables)
> > https://www.dokuwiki.org/plugin:complex_lists (lists)
> > https://www.dokuwiki.org/plugin:yalist (lists)
> >
> > Itemtable is for tables and you basically name your columns and then
> > add a bit of syntax to say you're giving the content for such column and
> > such row.
> >
> > Exttab3 brings mediawiki's syntax for tables. The syntax is quite ugly
> > but it's needed to be able to put block breaks inside table cells.
> >
> > Complex_lists and yalist, I don't know. I haven't had time to check them
> > yet. Not sure which one is better. I think there's a another plugin; in
> > any case there's one which makes it possible to "resume" a list (this is
> > most visible when you use numbered lists: it resumes the numbering).
> > Need to spend a bit more time on that but I can't until tonight.
>
> ok.
Complex_lists hasn't been updated in a while so that leaves yalist only.
It's possible itemtable has a few issues (hasn't been updated that
recently) but overall I don't have a preference for one over the other
between itemtable and exttab3.
So exttab3 and yalist?
--
Adrien Nader
------------------------------------------------------------------------------
BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT
Develop your own process in accordance with the BPMN 2 standard
Learn Process modeling best practices with Bonita BPM through live exercises
http://www.bonitasoft.com/be-part-of-it/events/bpm-camp-virtual- event?utm_
source=Sourceforge_BPM_Camp_5_6_15&utm_medium=email&utm_campaign=VA_SF
_______________________________________________
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
