1--- 2layout: spec-page 3title: "README: Draco Spec Authoring Information" 4--- 5 6<ol class="breadcrumb"> 7 <li class=""><a href="..">Home</a></li> 8 <li class=""><a href=".">Draft Specification</a></li> 9 <li class="">README</li> 10</ol> 11 12 13 14 15 16# Authoring Info, Draco 3D Bitstream Specification 17{:.no_toc} 18 19This document, once published, will define the Draco 3D Geometry Compression 20bitstream format and decoding process. 21 22**Contents** 23 24* TOC 25{:toc} 26 27The document is built from plain text section and subsection [Markdown] files 28(more specifically, [kramdown] files) using the [Jekyll] static site building 29tool. GitHub supports Jekyll natively. 30 31The `docs/` directory of this project is meant to contain only documentation 32and web content. The commands below should be issued from `docs/`. We do not 33want to pollute the code tree with Ruby and Jekyll config information and 34content. 35 36The `docs/spec/` directory contains the files needed to work on this 37specification document. 38 39 40## Building Locally 41 42Contributors will want to preview their edits locally before submitting pull 43requests. Doing so requires a sane Ruby and rubygems environment. We use [rbenv] 44and [bundler] to "groom" the project environment and avoid conflicts. 45 46_**Important:** All commands are to be run as an ordinary, unprivileged user._ 47 48 49### Ruby and rbenv 50 51This project currently depends on Ruby v2.3.0. Because your distro may lack this 52version -- or installing it may conflict with your system's installed version -- 53first **[install rbenv]**, then install Ruby v2.3.0 within it (again, in 54userland). 55 56~~~~~ 57# list all available versions: 58$ rbenv install -l 592.2.6 602.3.0-dev 612.3.0-preview1 622.3.0-preview2 632.3.0 64 65# install a Ruby version: 66$ rbenv install 2.3.0 67~~~~~ 68 69 70### Bundler 71 72Gem dependencies are managed by [bundler]. 73 74~~~~~ 75$ gem install bundler 76 77# Filesystem location where gems are installed 78$ gem env home 79# => ~/.rbenv/versions/<ruby-version>/lib/ruby/gems/... 80~~~~~ 81 82 83## Fork and Clone the Repo 84 85First, use the **Fork** button on the repo's [homepage] to fork a copy to your 86GitHub account. 87 88Second, clone your fork locally: 89 90~~~~~ 91git clone git@github.com:<username>/draco.git 92cd draco 93~~~~~ 94 95_**Note** that we **strongly** recommend [using SSH] with GitHub, not HTTPS._ 96 97Third, add a Git remote `upstream` that points to google/draco: 98 99~~~~~ 100git remote add upstream git@github.com:google/draco.git 101~~~~~ 102 103Your local repo with then have two remotes, `upstream` pointing at the 104authoritative GitHub repo and `origin` pointing at your GitHub fork. 105 106~~~~~ 107$ git remote 108origin 109upstream 110 111$ git remote show origin 112* remote origin 113 Fetch URL: git@github.com:<username>/draco.git 114 Push URL: git@github.com:<username>/draco.git 115 HEAD branch: master 116 Remote branch: 117 master tracked 118 Local branch configured for 'git pull': 119 master merges with remote master 120 Local ref configured for 'git push': 121 master pushes to master (up to date) 122 123$ git remote show upstream 124* remote upstream 125 Fetch URL: git@github.com:google/draco.git 126 Push URL: git@github.com:google/draco.git 127 HEAD branch: master 128 Remote branch: 129 master tracked 130 Local ref configured for 'git push': 131 master pushes to master (up to date) 132~~~~~ 133 134[**See this page**][1] for a longer discussion of managing remotes and general 135GitHub workflow. 136 137**Important: The following commands should be issued from the `docs/` 138directory.** 139 140 141### Set Local Ruby Version (rbenv) 142 143_**In the `docs/` directory**_ of your local clone, do: 144 145~~~~~ 146rbenv local 2.3.0 147~~~~~ 148 149Regardless of any other Rubies installed on your system, the project environment 150will now use v2.3.0 and gems appropriate for it. 151 152 153### Install Gem Dependencies with Bundler 154 155In the `docs/` directory of your local clone, run 156 157~~~~~ 158bundle install 159~~~~~ 160 161Bundler will set dependencies and install needed gems as listed in 162`Gemfile.lock`. 163 164_**Note** that you may need Ruby development headers installed on your system 165for some gems to compile successfully._ 166 167 168### Build and Preview Locally with Jekyll 169 170~~~~~ 171bundle exec jekyll serve 172~~~~~ 173 174This will build the documentation tree and launch a local webserver at 175`http://127.0.0.1:4000/docs/` (by default). Jekyll will also watch the 176the filesystem for changes and rebuild the document as needed. 177 178 179## **Markdown & Formatting Conventions** 180 181The spec document is composed mostly of syntax tables, styled with CSS. Mark 182them up as follows: 183 184 * Use the [fenced code block][fenced] kramdown syntax: A line beginning with 185 three or more tildes (`~`) starts the code block, another such line ends it. 186 187 * Use kramdown's [inline attribute syntax][inline] to apply the CSS class 188 `draco-syntax` to your code block by placing `{:.draco-syntax }` on the line 189 immediately after the code-block closing delimiter. 190 191 * Some syntax elements as annotated with their type and size in a right-hand 192 column. In your text editor, position these annotations at column **86**. 193 194**Example:** 195 196<pre><code>~~~~~ 197DecodeHeader() { 198 draco_string UI8[5] 199 major_version UI8 200 minor_version UI8 201 encoder_type UI8 202 encoder_method UI8 203 flags 204} 205~~~~~ 206{:.draco-syntax}</code></pre> 207 208... **will render as:** 209 210 211~~~~~ 212DecodeHeader() { 213 draco_string UI8[5] 214 major_version UI8 215 minor_version UI8 216 encoder_type UI8 217 encoder_method UI8 218 flags 219} 220~~~~~ 221{:.draco-syntax} 222 223 224## General GitHub Workflow 225 226Always do your work in a local branch. 227 228~~~~~ 229git co -b my-branch-name 230## work ## 231git add <filenames or -A for all> 232git ci -m "Reasonably clear commit message" 233~~~~~ 234 235Push your branch to `origin` (your GitHub fork): 236 237~~~~~ 238git push origin my-branch-name 239~~~~~ 240 241Next, visit the `upstream` [homepage]. If you are logged-in, GitHub will be 242aware of your recently pushed branch, and offer an in-page widget for submitting 243a pull request for the project maintainers to consider. 244 245Once your pull request is merged into upstream's master branch, you may 246synchronize your clone (and remote `origin`) as follows: 247 248~~~~~ 249git co master 250git fetch upstream 251git merge upstream/master 252git push origin 253~~~~~ 254 255Your old working branch is no longer needed, so do some housekeeping: 256 257~~~~~ 258git br -d my-branch-name 259~~~~~ 260 261 262[Markdown]: https://daringfireball.net/projects/markdown/ 263[kramdown]: https://kramdown.gettalong.org/ 264[Jekyll]: https://jekyllrb.com/ 265[rbenv]: https://github.com/rbenv/rbenv 266[bundler]: http://bundler.io/ 267[install rbenv]: https://github.com/rbenv/rbenv#installation 268[homepage]: https://github.com/google/draco 269[using SSH]: https://help.github.com/articles/connecting-to-github-with-ssh/ 270[1]: https://2buntu.com/articles/1459/keeping-your-forked-repo-synced-with-the-upstream-source/ 271[fenced]: https://kramdown.gettalong.org/syntax.html#fenced-code-blocks 272[inline]: https://kramdown.gettalong.org/syntax.html#block-ials 273 274
