Hi, When I use "Markdown" I mean those tools that are common in *at least* the implementation of the core definition at https://daringfireball.net/projects/markdown/syntax - I do not mean the concept of a simplified text markup.
It is trivial to identify if a syntax complies to this and most of those with "markdown" in the title do so - github flavoured markdown - php markdown extra are a couple of popular ones (that happen to have extensions in common as well, but that's a bonus). Markdown as inspired bu John Gruber, is becoming somewhat standard and that allows us to expect interoperability greater than if we use a specific wiki format. I would like to be able to embed our API documentation into Edi - others (Samsung for example) would like to be able to embed it elsewhere. Our documentation writers would like to use a preview based editor so that their lives are not text based for the duration of the project (did I mention that markdown editors in dokuwiki support live preview?). There are many things possible if we use a more common format. At the same time it does not remove functionality like including other pages or editing online - I don't say that out of opinion, I have the plugin loaded here and can use it as stated. Why do you assert that the benefits I listed are not possible? Andrew On Wed, 18 Oct 2017 at 10:57 Carsten Haitzler <ras...@rasterman.com> wrote: > On Wed, 18 Oct 2017 09:17:05 +0000 Andrew Williams <a...@andywilliams.me> > said: > > https://en.wikipedia.org/wiki/Markdown > > specifically GFM vs commonmark. github call it markdown. stackoverflow's > markdown is commonmark. they are not compatible (strikethrough, tables > etc.) ... there is no SINGLE markdown nor {"official one" github markdown > != > stackoverflow (common mark) != remark (it is a markdown... of some sort > that's > partly compatible), vs trac vs dokuwiki vs mediawiki vs... they all use a > markdown of some sort. a shorthand generally simple/compressed metadata > definition within a text file that's less strict and simpler than > something like > html. > > i am disagreeing that there is a single specific common makrdown format > that is > magically going to work everywhere markdown is used. > > if you want to say "commonmark" is the spec then > http://spec.commonmark.org/0.28/ doesn't to my scan define any way to > include > other files like dokuwiki markdown does, for example. so what you say > works is > seemingly non-standard markdown, so you're back to custom markdown's again > that > are dependent on the wiki engine they run in. > > i know dokuwiki is both the wiki engine and a specification for the > markdown it > understands. it's actually kind of a mix of markdown and markup with > somethings > being html-like tags and others more like markdown... but i know the name > refers to both. > > my point is now you are going to introduce a different markdown format > that ... > is not going to be compatible with other markdown engines (as above) or is > not > going to have the kinds of features needed to allow editing online what is > a > mix of generated non-editable and editable blocks of content (the includes > solve/allow for this for example). > > so i'm not sure where you are going with this. it seems to just bring > complexity (more markdown formats) without the benefits you claim (see > above). > > > Hi, > > > > I am struggling with the factual inaccuracies - phab is not markdown > (they > > call it "similar to" > > https://secure.phabricator.com/book/phabricator/article/remarkup/), > trac is > > not markdown (it is inspired by previous wikis > > https://trac.edgewall.org/wiki/WikiFormatting) but all of this is > > irrelevant to the point. > > > > MarkDown is a common format that many have extended. Case in point - we > > were working on some documentation last night and one of the group did > not > > want to put it in the wiki yet so they uploaded it to github temporarily. > > And you know what? Their web engine automatically formatted it correctly > - > > I then loaded it into dokuwiki with markdown enabled and the same thing - > > the content, heirarchy, markup and syntax highlighting all just worked. > > Whether we like it or not GitHub has changed the way that people think > > about social coding and their adoption of Markdown has had a big impact > on > > people using it as a standard (there are book authoring systems and > > presentation apps using it as the main format). > > > > What I was proposing is to use MarkDown instead of Dokuwiki syntax (due > to > > the benefits already listed) and this has no bearing on the choice of > > dokuwiki or the functionality - it is merely the syntax used. Online > > editing works just as well, page includes also work through "frontmatter" > > much as before. Your assertion that using any other format makes it > > uneditable seems completely untrue - what is causing your concern here? > > > > Is it possible that in this discussion we have confused the word dokuwiki > > as a format and dokuwiki as a product? > > > > Thanks, > > Andrew > > > > On Wed, 18 Oct 2017 at 02:03 Carsten Haitzler <ras...@rasterman.com> > wrote: > > > > > 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 > > > > > > -- > > 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 ------------------------------------------------------------------------------ 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
