Re: [E-devel] Documentation into the Interfaces era :)

[Carsten H. <ra...@ra...>]

On Thu, 19 Oct 2017 09:28:16 +0000 Andrew Williams <an...@an...> said:

> Hi,
> 
> I don't understand the hypothetical edit problem - it works here and I see
> no issues. Perhaps you can give a concrete example that you are worried
> about (i.e. a page we have) and I will check that it works as expected?
> 
> To satisfy the addition of dokuwiki includes, title etc the plugin
> recognises "front matter" (as I mentioned before) this is not in the
> standard but is quite common - jekyll and others do this to. That segment
> can be ignored by a markdown parser if edited outside dokuwiki but allows
> non-standard things like includes etc to occur.

this is the bit i'm getting at. it's not in the standard, but your goal is to
"follow the standard". if you do follow it then you can't use such non-standard
features. then things begin to get very limited.

> Thanks,
> Andrew
> 
> On Thu, 19 Oct 2017 at 01:04 Carsten Haitzler <ra...@ra...> wrote:
> 
> > On Wed, 18 Oct 2017 10:34:04 +0000 Andrew Williams <an...@an...>
> > said:
> >
> > > 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
> >
> > well for starters includes are not part of:
> >
> > https://daringfireball.net/projects/markdown/syntax
> >
> > using just this "minimal markdown standard" will lead to issues allowing
> > it to
> > be editable (eg edit body but not the format/template). how will it be
> > sane to
> > have a format/template for a page read-only but have body editable? at
> > least
> > that is how i was originally seeing docs being laid out by using includes
> > to do
> > this. you say it doesn't remove including of pages ... yet the markdown
> > doesn't
> > support that as you point out... this is what has got me going "this doesnt
> > seem like a great idea".
> >
> > if you do use includes (and the markdown plugin can handle both dokuwiki
> > format
> > AND your flavor of markdown above at the same time ... which somehow seems
> > odd
> > if it did), then these non-standard dokuwiki things are not interoperable
> > with
> > tools and other things etc. ... ?
> >
> > i'm having trouble reconciling the above.
> >
> > > On Wed, 18 Oct 2017 at 10:57 Carsten Haitzler <ra...@ra...>
> > wrote:
> > >
> > > > On Wed, 18 Oct 2017 09:17:05 +0000 Andrew Williams <
> > an...@an...>
> > > > 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 <ra...@ra...>
> > > > wrote:
> > > > >
> > > > > > On Tue, 17 Oct 2017 10:31:34 +0000 Andrew Williams <
> > > > an...@an...>
> > > > > > 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 <
> > ra...@ra...>
> > > > > > wrote:
> > > > > > >
> > > > > > > > On Mon, 16 Oct 2017 09:25:20 +0000 Andrew Williams <
> > > > > > an...@an...>
> > > > > > > > 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 <
> > > > ra...@ra...
> > > > > > >
> > > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > > On Tue, 10 Oct 2017 17:53:09 +0000 Andrew Williams <
> > > > > > > > an...@an...>
> > > > > > > > > > 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
> > > > > > > > > > > enl...@li...
> > > > > > > > > > >
> > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > > --
> > > > > > > > > > ------------- Codito, ergo sum - "I code, therefore I am"
> > > > > > > > --------------
> > > > > > > > > > Carsten Haitzler - ra...@ra...
> > > > > > > > > >
> > > > > > > > > > --
> > > > > > > > > http://andywilliams.me
> > > > > > > > > http://ajwillia.ms
> > > > > > > >
> > > > > > > >
> > > > > > > > --
> > > > > > > > ------------- Codito, ergo sum - "I code, therefore I am"
> > > > > > --------------
> > > > > > > > Carsten Haitzler - ra...@ra...
> > > > > > > >
> > > > > > > > --
> > > > > > > http://andywilliams.me
> > > > > > > http://ajwillia.ms
> > > > > >
> > > > > >
> > > > > > --
> > > > > > ------------- Codito, ergo sum - "I code, therefore I am"
> > > > --------------
> > > > > > Carsten Haitzler - ra...@ra...
> > > > > >
> > > > > > --
> > > > > 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
> > > > > enl...@li...
> > > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
> > > >
> > > >
> > > > --
> > > > ------------- Codito, ergo sum - "I code, therefore I am"
> > --------------
> > > > Carsten Haitzler - ra...@ra...
> > > >
> > > > --
> > > http://andywilliams.me
> > > http://ajwillia.ms
> >
> >
> > --
> > ------------- Codito, ergo sum - "I code, therefore I am" --------------
> > Carsten Haitzler - ra...@ra...
> >
> > --
> http://andywilliams.me
> http://ajwillia.ms


-- 
------------- Codito, ergo sum - "I code, therefore I am" --------------
Carsten Haitzler - ra...@ra...