On Tue, 17 Oct 2017 10:31:34 +0000 Andrew Williams <a...@andywilliams.me> said:
> Googling "is dokuwiki markdown?" returns a dokuwiki page stating "Markdown > is a text markup language. So is DokuWiki syntax. Or MediaWiki syntax. > There are similarities but none of them is a dialect of the other". > The standards page https://tools.ietf.org/html/rfc7763 lists > http://daringfireball.net/projects/markdown/ as the original source and > https://tools.ietf.org/html/rfc7764 lists recognised extensions including > https://michelf.ca/projects/php-markdown/extra/ and > https://help.github.com/articles/github-flavored-markdown/ but nothing > about dokuwiki. > So you'll forgive me for saying that you calling dokuwiki syntax markdown > does not make it so. well i listed examples. i've been through many markdown wiki systems over the years and none have been compatible (partially yes, totally - no). all are described as markdown. phab has markdown... and it was incompatible with trac, both of which are incompatible with mediawiki and so on... but they share some similar elements and ideas common to markdowns like: this **is bold** or //italic// (maybe they use '' or -- or other chars but the idea is core to markdown variants). my point here is... dokuwiki is the wiki we're using. to allow docs to be editable on a wiki we have to commit to the formatting of that wiki as being "the format" because otherwise it's not editable. sure. add more plugins more more formats but then you just added "yet another markdown" format and we now have to deal with 2 of them in the same wiki. > Interoperability is good for us all. It means we can easily change tooling > if we need to, it means the learning curve is lower and it means we can do > cool things like embedding it in Edi etc as the format is well recognised > etc. that just does not exist in the wiki world. see above. > I agree with all the ideals of editing online etc etc - the choice of > format should make no difference here as the dokuwiki is pretty simple even > for their chosen format no? > Andrew i frankly don't much care what the format is... but i chose dokuwiki because it had all the elements needed to be able to build a documentation system already. it could include multiple sources into a single page (thus allowing some parts of a page to be editable, others not and be a generated template). etc. ... by switching to something else we now have to redo all that evaluation etc. :( > On Mon, 16 Oct 2017 at 20:53 Carsten Haitzler <ras...@rasterman.com> wrote: > > > On Mon, 16 Oct 2017 09:25:20 +0000 Andrew Williams <a...@andywilliams.me> > > said: > > > > > Hi, > > > > > > Unfortunately dokuwiki is not markdown - > > > > Well... it is markdown AND markup with an eclectic mix of both. there > > isn't a > > single markdown format. every wiki has it's own which is slightly > > different, > > but commonly they have very short ways to do a link (especially inside the > > wiki), and use **, //, for bold/italic or similar, equals for headlines > > etc. ... so i'd call it markdown. it is a very specific kind of markdown. > > > > > https://www.dokuwiki.org/wiki:syntax , what I was proposing moves us to > > the > > > php extended markdown which is well known and supported by most php based > > > apps if not more. > > > By changing to a standardised format we can have better interoperability > > > and also have our auto generated docs integrate into the website much > > > better. > > > > why do we need interoperability? the docs really only have one main > > purpose. > > to be displayed by dokuwiki. as i gather you are proposing to put content > > into > > the dokuwiki content tree ... and that by definition is dokuwiki > > markdown/up/whatever ... > > > > one of the ideas for our documentation was to have the docs be live > > editable > > content on the wiki and auto-generation from source is really all about > > building the templates and raw "code content" then having sections that are > > user editable along even with user discussion threads. the php doc site > > works > > this way so questions and answers about apis, classes or topics stay > > together > > with the docs and become part of them. if the docs on something could be > > improved, any user can improve them just by editing the wiki. thus i see > > the > > need to have the wiki format be consistent and the docs are very closely > > tied > > to dokuwiki. > > > > > As for languages the figuring was that we have a specific list of > > supported > > > languages for the new interfaces work. I may have missed a line or two as > > > there was nothing to add or I forgot - but we could be more explicit for > > > sure. > > > What do the community think are our official supported languages? We > > have a > > > lot of manual binding or external contributions so it’s kind of hard to > > > tell... > > > > I'd say lua is probably the most important and interesting. it's already > > used > > for documentation generation. it's used inside efl (edje and evas > > filters). it > > also is the only language other than c++ that doesn't need extra > > dependencies > > beyond what efl already has. we have libelua even as an easy front end to > > use > > for using lua script in your code. c++ i'd say is a very close second > > since it > > also needs now extra dependencies and we already build by default out of > > the > > box like we do with lua. the next batch would be python (which we have no > > generators for in tree yet) and js (node.js/v8), with c# at the end ATM. > > > > > Thanks, > > > Andrew > > > On Mon, 16 Oct 2017 at 05:48, Carsten Haitzler <ras...@rasterman.com> > > wrote: > > > > > > > On Tue, 10 Oct 2017 17:53:09 +0000 Andrew Williams < > > a...@andywilliams.me> > > > > said: > > > > > > > > > Hi, > > > > > > > > > > I am looking at how we should be trying to structure our > > documentation as > > > > > we update for interfaces and slowly move aside the legacy pages. > > > > > > > > > > I've made this page to summarise my thinking so far - capturing what > > we > > > > > should migrate, what we should add and a few items that don't seem > > to fit > > > > > yet in the new structure. I have linked tickets from the main doc > > > > > improvement task as well to see how much we've got covered. > > > > > > > > > > https://phab.enlightenment.org/w/doc_system/doc_structure/ > > > > > > > > what about lua? and c++? at least your sample list seems to be a bit > > > > inconsistent with languages in sections. is this intended? or just an > > > > oversight? > > > > > > > > > Please let me know what you think - I hope this is heading in the > > right > > > > > direction. Of note is that it splits the dev docs out from the user > > docs > > > > > which will also make it easier to transition :) > > > > > > > > comment about .md.txt vs .txt - why? everything in the wiki is already > > > > .txt and > > > > it's markdown by definition... if you create a wiki page its always > > just > > > > .txt > > > > when going through the web ui... why change the pattern already there. > > i > > > > also > > > > am not sure the urls to pages will come out nicely if its .md.txt > > instead > > > > of > > > > just .txt. e.g.: > > > > > > > > https://www.enlightenment.org/docs/c/start > > > > > > > > is the url for docs/c/start.txt > > > > > > > > otherwise i see no issues with what you put there. :) > > > > > > > > > Cheers, > > > > > Andy > > > > > -- > > > > > http://andywilliams.me > > > > > http://ajwillia.ms > > > > > > > > > > > ------------------------------------------------------------------------------ > > > > > Check out the vibrant tech community on one of the world's most > > > > > engaging tech sites, Slashdot.org! http://sdm.link/slashdot > > > > > _______________________________________________ > > > > > 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" > > -------------- > > > > Carsten Haitzler - ras...@rasterman.com > > > > > > > > -- > > > http://andywilliams.me > > > http://ajwillia.ms > > > > > > -- > > ------------- Codito, ergo sum - "I code, therefore I am" -------------- > > Carsten Haitzler - ras...@rasterman.com > > > > -- > http://andywilliams.me > http://ajwillia.ms -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- Carsten Haitzler - ras...@rasterman.com ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
