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. 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? 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? > > 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. > > 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. > > - 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. > > - 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. > > - 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. -- 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
