AsciiDoc conversion experiments #682
Conversation
The sup element breaks the auto-conversion to AsciiDoc
|
The current state is that it contains a |
…rsion-experiments
|
I'll mark this as "ready for review" now. There certainly are still some issues (probably some links not working), or possible improvements (as in ~"That's not how you do this in AsciiDoc!"), but it should currently be a reasonably consistent state. A summary of some possibly relevant points:
Previews of the resulting specifications are attached here. The PDF file was compressed (as described in the build instructions). For the HTML version, I downscaled/compressed the images, but the HTML file can just be dropped into the local |
| @@ -0,0 +1,3262 @@ | |||
|
|
|||
There was a problem hiding this comment.
Could the property references be grouped together in a more consistent way, like tileset properties first, then tile format properties, then metadata - roughly based on the folder structure on github? I think it will be easier to follow that way.
There was a problem hiding this comment.
Right now, this is listed alphabetically by the "type name", e.g.
...
templateUri (linked)
tile (linked)
tile.implicitTiling (linked)
tileset (linked)
...
Of course, abritrary other orders can be established (e.g. sorting by the "Title" - i.e. the string that is actually displayed at the end). But when it comes to "grouping" and "folders", I'll have to see how the "desired sorting" can be squeezed into wetzel - beyond the this.knownTypeNames = Object.keys(this.knownTypes).sort(); that it is doing now...
There was a problem hiding this comment.
@javagl any update on this one? It doesn't need to hold up the PR, I'm just curious.
specification/BUILDING.md
Outdated
| - Run the following command: | ||
| ``` | ||
| "C:\Program Files\gs\gs9.20\bin\gswin64.exe" ^ | ||
| -dPrinted=false ^ | ||
| -sDEVICE=pdfwrite ^ | ||
| -dCompatibilityLevel=1.4 ^ | ||
| -dPDFSETTINGS=/screen ^ | ||
| -dNOPAUSE ^ | ||
| -dBATCH ^ | ||
| -dDetectDuplicateImages ^ | ||
| -sOutputFile=Specification-1.1.0-compressed.pdf ^ | ||
| Specification-1.1.0.pdf | ||
| ``` | ||
| (This is a Windows .BAT file. On Linux, replace the `^` with `\`) |
There was a problem hiding this comment.
My notes on the build process on Linux:
- I had to build Ghostscript from source since I couldn't find precompiled Linux binaries. I downloaded
ghostscript-9.20-linux-x86_64.tgz, ran./configure, thenmake, and that createdbin/gs. - Have you seen this warning? I'm not sure which character it's refering to.
~/Code/3d-tiles/specification$ asciidoctor-pdf --verbose --trace --attribute scripts=cjk --attribute pdf-theme=default-with-fallback-font Specification.adoc --out-file Specification-1.1.0.pdf
asciidoctor: WARNING: Could not locate the character `' (\u2063) in the following fonts: Noto Serif, M+ 1p Fallback, Noto Emoji
There was a problem hiding this comment.
I saw that warning, and tried to figure out where it came from, but my friggin Windows console just displayed this as "�" and did not include the info that it was \u2063, so I couldn't properly search for this. I'll take a note for that as well, the Unicode code may be helpful to figure out what this actually is... "Invisible Separator" for now, but I'll have a look...
|
I wrote some comments to the inlined ones, and summarize them as a short TODO list here:
|
|
An aside: I added the logo and an introductory sentence to the (GitHub-rendered version of the) This new "top-level" README.md could then be something like SpecificationHi there, look, all this is ADOC now, here's the entry point for 3D Tiles 1.1: MAIN_SPECIFICATION.md Here are some PDF files: Specification-1.1.0.pdf ... ... so that this directory/README.md rather serves as "the entry point" for all spec-related documents (similar to https://github.com/KhronosGroup/glTF/tree/main/specification ) (Not a strong opinion, just a thought...) |
Eventually this might make sense, but it is another level of indirection that I don't think is worth it right now. |
|
The latest commits remove the now obsolete One thing that I remembered while doing this: Some of the Markdown documents contained a local Table Of Contents (e.g. the Using the |
|
Let's skip the TOC for now. |
|
I noticed a lot of changes when I generated the property reference with wetzel locally. Does the property reference need to be re-generated now that #688 is merged? |
|
Indeed, the state here was generated based on a state without |
|
Thanks @javagl! A huge amount of work went into this and I'm glad to see it merged. |
A DRAFT of the first experiments for converting the specification to AsciiDoc (see #590 )