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. yes - docs are meant for stable releases - whatever next release is is the goal. we could take a policy of "api is not stable until documented". that's actually not a bad idea. it pushes people to document it as it'll be generated with a default template that says "this is unstable and should not be used" :0 i like this idea。 :) we can disable or even remove apis that dont get filled in with docs easily. find the ones that are still in template mode after a while. > 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. > > > 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? it applies to the entire wiki - every single page on www.enlightenment.org. if there is a <code> block - it can auto-link to the correct reference (based on language and if we generate it). > We can also mod_rewrite or something else to turn docs/ecore/foo/bar > into whatever we want if needed. I think that for a namespaced > organization, a trailing /api component would only be a redirect or a > simple page with a list of entries but not much content by itself. > > > 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. > > I don't think it's worth spending time on it for now. It can always be > done later on without costing more time if really needed. Let's wait and > see. not bothering right now. if i want things linked.. i make <code c> blocks. :) > > > 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? per page we import from tizen docs - they come with a respective licence. no need to place any on pages freshly made in dokuwiki (we can have a global license cover that) > > > The documentation in Tizen is really good. I'm totally unbiased on > > > that. No, really. > > > > sure... :) > > Who cares about typos and the like anyway? Being rushed is like a proof > of authenticity of any real project: if you don't rush, it only means > you had too much time. > > > > 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. > > Quite likely it got impacted by that. Well, too late and not worth > bothering. You can't see it but I got to see what some of the annoyances > were going to be. > > > > 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 > > 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. well i have something up already - let's munge on that. :) > > > 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. plugin not installed. exttab3 is now. :) > > > - 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? > > With DW syntax, if I want a linefeed in a list item, I need to write it > as: > * foo bar\\ this gets on a newline > > It's not readable when editing. > > Quite often when you get to lists with lots of content in each item, > you're doing it wrong and would better use sections or re-think your > prose but there's still this 10% of time when it's really what makes > most sense. > > > > - 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). > > Hah, true. I should really install a vim plugin for the text edit boxes > if I intend to do anything serious from the browser. yup! :) > > > - 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. > > Confirmed: I now get the file browser button. :) > > > > - 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 > > The most annoying thing to lose is links because they're in the middle > of the text but since we're not going to keep the same structure we'll > need to check links. > > It's a bit depressing but until there's at least 30% of the content > imported, links will be in a very sad state. That's basically what > happened when we wrote that documentation: we could add a link from A to > B but then B would change name or it hadn't been written yet and would > never be named that way. So, well, realistically it'll be done with > proof-reading at a slightly later stage. indeed. > > > - 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. complex_lists as a plugin is just broken. naming is actually illegal (cant have _'s in the plugin name) and i frankly couldn't be bothered fixing it all. so yalist it is. the others are in (itemtable and exttab3) -- ------------- 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
