Official documentation site!

[iiceman]

And then have a function to export that data as html, markdown OR xml with the help of a webservice so everybody will be happy

[Wingnut]

That's right, John!  And you, too, Ice!  And thanks for the like, Dad72.  It's nice to have a few friends standing around the quicksand pit, watching me sink.  hehe.

 

Well thought, John... the user or editor doesn't see the xml at all.  He/she just creates or edits a data object in a web form.  No writing markdown or html or xml... just text.  Behind the scenes, the editing app knows what object type it's editing, knows how to turn it into xml or store the data on a JSON object. The editor app can edit a single xml node or json prop, or an entire document of xml nodes (entire json/php object).  The doc/node creator just classifies the node(s)... textblock, codeblock, codeinline, textinline, imageblock, imageinline, etc.  Those are the element names And data class types)... we can make-up any xml element names we want.  It's our markup language.

 

If each doc is a json/php object, that object carries a template with it... that tells the intended order of data (and which data is included). 

 

20 years back when we were making moo objects into html and vrml, we used two props called .hassembly and .vassmbly.  Each was an array of strings or identifiers... that was the ORDER used to present the data in the markup... and it also told WHICH data on the object... was to be marked-up.  We used methods called html() and vrml() as our markup-type determiners.  Call object.html(), and you get html markup representing the object.  Same with object.vrml() for a vrml markup.  All dynamically generated... only when browsed-for.  No static .md anywhere.

 

Ice, the problem with your idea... is that the BD proggers are converting all the .ts to .md in a pre-done batch pass.  Instead of this, they would need to make the .ts into objects, and then each object could have a .toXML(), and .toMD(), and why not a .toWebGLDynamicTexture() for those who want to read docs while being inside their virtual worlds. 

 

Using this method, just think of the power of language translation we would have, if we wanted to use it.  On the fly translation of text blocks and picture captions... to any language. 

 

Yes, XML still has its drawbacks, and let it be known that I would be perfectly happy with all .md, but we sure lose a ton of power by doing it that way.  This converting of .ts to .md doesn't seem to come up for discussion and pondering.  In BD1, it was just plain done that way.  In BD2, again, it's just plain done that way, and nobody seems to have a say in that move. 

 

Once they hard code BD into being that way, there's no chance for recovery.  It could have been a huge mistake, but nobody is checking it for being a huge mistake.  It's called being "railroaded" into a certain way of doing things, and I'd really like to ask the person who thought it up... if we are allowed to try to convince them of a better way.

 

I'm just a fart in a windstorm as far as being a worthy expert in these matters.  I'm far from an XML/XSL pro.  Thank you to John and Ice for at least trying to weigh XML fairly and consider it's power.  I'll be plenty happy with an all-markdown solution... IF XML gets fair weighing and possible future consideration.  It starts... by NOT converting the .ts into markdown.  Please store them as .ts-generated PHP or JSON objects... which can output markdown at browse time, not pre-batch.  By doing on-the-fly markup generation, we AT LEAST have a future chance of using markup other than .md. 

 

Any chance?  Thanks.  By the way, don't take me too seriously.  I might huff and puff during a campaign to get a change made, but I'm not seriously emotional over this issue.  Temechon and crew have done us well, but I still get to question the logic behind certain things.  It's one of the inalienable rights of having a typing machine, right?  Temechon, you can concentrate on tsDocObj.toMD() and continue your efforts without the batch conversion. 

 

I guess you'll still do a batch run on the .ts, but they'll be made into objects, not .md documents.  Consider it?  Please?  Someday later, if nobody else codes it, I will code tsDocObj.toXML() and .toHTML(), as wanted. 

 

This is Iceman's idea... not mine. (Wingy ducks and covers)    I think it's a good idea.  Later, we'll do the same thing with tutDocObj's... right?    (the tutorials/otherdocs).  They would no longer be markdown docs.  Instead, they are JSON objects that can present themselves in many different ways, and are edited with a new thing called the JSON Document Editor.  Wow!

 

Sigh.  Let's give people the chance to clear markdown out of their lives.  If we MUST use an html-abbreviating system, let's use one that has the power to format documents properly and not leave JC out in the cold.... looking for a simple float-text.  Something that can make decent tables.  Something that doesn't screw up bullet lists.  Something that doesn't chop-off the bottom of documents.  Whatever it was that welded you guys into a markdown-or-else frame of mind... PLEASE consider breaking that weld and then analyzing what made you guys weld-onto that idea in the first place.    Thanks.

[Temechon]

Wingnut, 

 

Markdown is parsed into HTML before being rendered in the browser... And more: you CAN use HTML in a MD file. Isn't it awesome ?

So why add HTML tags into the document whereas it's being done automatically ?

[Wingnut]

I give.    I can't seem to explain the virtues of XML.  It's not worth the hassle. 

 

So, what was it that made folks climb aboard markdown so fervently?  Was it github?  HTML/XML/SGML is, by far, the most popular document markup method.  FAR more people know HTML than know markdown.  What made you guys become markdown fans? 

 

I guess I just don't see the benefits to markdown.  It's common for me to be blind, though.

 

I'm off to PUSH a chain down the street.  That will surely be easier than figuring out this markdown epidemic. 

[jahow]

I don't think you can really compare markup languages (HTML, XML) with markdown. MD is not truly a language, it just allows you to use some symbols to add formatting to a raw text. You can write an article with text only and it will still be readable by MD.

 

It's just so much more user-friendly than a markup language. As far as I'm concerned, writing stuff in HTML is always a pain down there: where to put <br/>, what tag to use (span, p, strong, em, hX...), put an ID or class, and let's not talk about tables. As for XML well I guess you'd need to know the associated XSL stylesheet, and constantly refer to it when writing content. And these two languages are so strict... syntax checking shouldn't be part of writing an article.

[JohnK]

Just been using the new documentation site, first impressions are good. One thing that fooled me at first was clicking on, for example, 01 Playpen Tutorials and waiting for a new page to load. It took me a while to realise I needed to scroll down to get the list of tutorials as they appeared off-screen. Maybe a jump to the top of the list when a tutorial is selected? Perhaps I am just being a bit slow on the up take. What do others think?

[Temechon]

Nice idea !

Added to our backlog !

[Wingnut]

I had another big post here, but nah, wiped it.  Party on! 

[jerome]

the <html> tag is missing under <!DOCTYPE HTML>  in the first part of html code in the "Getting started" section  here : http://doc.babylonjs.com/

[JCPalmer]

 

JcPalmer... keep us posted in your search for floating text beside pictures, for markdown.  

 

Well, the best I could do is to use explicit <table> tags.  In general, I just paired images up using the '|' table short hand for space saving instead.  This works as long as you do not mix an image with text in the same row though.  The one instance I did used <table>, https://github.com/BabylonJS/Extensions/tree/master/TowerOfBabel#morphmesh-classes, I would not control the width to keep the image from shrinking, & could not set the border=0.  

 

Also tried style attributes, but never got them to achieve what I wanted.  Did not try a <div> approach, as I saw posts that said Github did not work correctly with those either.

 

Anyway, the documentation is done!  Doing my final checks prior to committing code.

[Wingnut]

Nice nice nice, Jc.  What a great doc.

[HugoMcPhee]

thankyou these docs are great!