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 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!) :) now adding auto-linking outside of code blocks is harder. problem: 1. we don't know language context (link in c, cpp, js, python, lua? which?) 2. a lot more work (likely write plugin to do it ... if we knew context). so q is - do i bother? or do we just leave it to links outside code sections not being automatic (have to manually [[]] things) ... which as i think about it i think is fine. we can FORCE every function to have a code section - an example at least. a "see also" section can be done in a code block as well so it links nicely. imho these solve the problem enough from a docs point of view. of course this consideration goes right to the heart of what our docs will look like formatting-wise as a standard. thus positing it here. > 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. > The documentation in Tizen is really good. I'm totally unbiased on > that. No, really. sure... :) > More seriously, it's fairly comprehensive and covers some topics which > are large enough for no-one to deal with them on their free time. > > It's made of "tutorials" and "programming guides". Programming guides > sit between tutorials and the API reference. Think of the tutorial as > "hold-my-hand-and-make-me-use-that-widget-for-the-first-time" while the > programming guide explains the common APIs and usage. Most widgets are > covered. > > For reference, my first try is a page with no incoming link at: > https://www.enlightenment.org/docs-non-api-wip doesn't work. i think you got the wiki when beber had it locked down and semi-broken for editing. it's back to working now. > The very first question I got was: how do we organize that > documentation? good q - partly... see above. > 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 > 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) > - there should be a plugin which provides mediawiki's table/list syntax > (there are several of them available, not sure which one to chose) yeah - i know of it. so far tables have been good enough, but yes - this can be added. what do you need it for? > - locating the words "tizen" and "appcore"/"app_core" is fairly > difficult and it'd be nice to have highlighting for that ummm spellchecker! grep. vi, emacs, ... if your browser has a spellchecker they'll hilight as they arent.. real words. :) but tbh - find-in-page in browser or copy & paste to a local vim/emacs editor and pre-edit there a bit before passing into browser editor (or get commit access and commit right to www-content git for a "mass import" of data as this is heavy back-end work that is why we have a gitbacked wiki). > - when I want to upload an image, I need to download it locally then > re-upload it (something for which I don't have the rights it seems) you .. should have the rights... a normal @user can do everything - unregistered (@ALL) can only read. the acl's say so.. maybe it was the above lock of wiki by beber. try again. > - we need to think about the license a bit in order to have something > compatible with the mix from tizen.org. as above - put license link at bottom of imported tutorials/whatever - leave as a separate example/tutorial/howto - that page has that license at the bottom listing origin and what license is is :) > What's annoying and probably won't change: > - copy-paste from tizen.org is a bit difficult because of tizen.org's > layout > - copy-paste loses some markup, in particular headers/titles, lists, > tables, figures manual - have to redo. :( it'll be done once all imported so going forward we're find long-term > - 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 > -- > 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 > -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ 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
