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. > 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. > > 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). > 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. > > > > 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. > > > 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. 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. :) > > > 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. > > > - 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. sure. > > > - 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. > > > > - 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. agreed - import linkless, then in proofread/editing, re-link. reality is we may add links that were not there before because it's a "good idea". it's not hard to do. it's a one-time thing. > > > - 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. > -- > 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
