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![Draco logo graphic](../artwork/draco3d-horiz-320x79.png)
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