| <!DOCTYPE html> |
| <html> |
| <head> |
| <meta charset="utf-8"> |
| <title>Apache Mesos - Markdown Style Guide</title> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| <meta property="og:locale" content="en_US"/> |
| <meta property="og:type" content="website"/> |
| <meta property="og:title" content="Apache Mesos"/> |
| <meta property="og:site_name" content="Apache Mesos"/> |
| <meta property="og:url" content="http://mesos.apache.org/"/> |
| <meta property="og:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/> |
| <meta property="og:description" |
| content="Apache Mesos abstracts resources away from machines, |
| enabling fault-tolerant and elastic distributed systems |
| to easily be built and run effectively."/> |
| |
| <meta name="twitter:card" content="summary"/> |
| <meta name="twitter:site" content="@ApacheMesos"/> |
| <meta name="twitter:title" content="Apache Mesos"/> |
| <meta name="twitter:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/> |
| <meta name="twitter:description" |
| content="Apache Mesos abstracts resources away from machines, |
| enabling fault-tolerant and elastic distributed systems |
| to easily be built and run effectively."/> |
| |
| <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet"> |
| <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml"> |
| <link href="../../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" /> |
| |
| |
| |
| <!-- Google Analytics Magic --> |
| <script type="text/javascript"> |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-20226872-1']); |
| _gaq.push(['_setDomainName', 'apache.org']); |
| _gaq.push(['_trackPageview']); |
| |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| </script> |
| |
| </head> |
| <body> |
| <!-- magical breadcrumbs --> |
| <div class="topnav"> |
| <div class="container"> |
| <ul class="breadcrumb"> |
| <li> |
| <div class="dropdown"> |
| <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel"> |
| <li><a href="http://www.apache.org">Apache Homepage</a></li> |
| <li><a href="http://www.apache.org/licenses/">License</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| <li><a href="http://www.apache.org/security/">Security</a></li> |
| </ul> |
| </div> |
| </li> |
| |
| <li><a href="http://mesos.apache.org">Apache Mesos</a></li> |
| |
| |
| <li><a href="/documentation |
| /">Documentation |
| </a></li> |
| |
| |
| </ul><!-- /.breadcrumb --> |
| </div><!-- /.container --> |
| </div><!-- /.topnav --> |
| |
| <!-- navbar excitement --> |
| <div class="navbar navbar-default navbar-static-top" role="navigation"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#mesos-menu" aria-expanded="false"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="navbar-brand" href="/"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo"/></a> |
| </div><!-- /.navbar-header --> |
| |
| <div class="navbar-collapse collapse" id="mesos-menu"> |
| <ul class="nav navbar-nav navbar-right"> |
| <li><a href="/gettingstarted/">Getting Started</a></li> |
| <li><a href="/blog/">Blog</a></li> |
| <li><a href="/documentation/latest/">Documentation</a></li> |
| <li><a href="/downloads/">Downloads</a></li> |
| <li><a href="/community/">Community</a></li> |
| </ul> |
| </div><!-- /#mesos-menu --> |
| </div><!-- /.container --> |
| </div><!-- /.navbar --> |
| |
| <div class="content"> |
| <div class="container"> |
| <div class="row-fluid"> |
| <div class="col-md-4"> |
| <h4>If you're new to Mesos</h4> |
| <p>See the <a href="/gettingstarted/">getting started</a> page for more |
| information about downloading, building, and deploying Mesos.</p> |
| |
| <h4>If you'd like to get involved or you're looking for support</h4> |
| <p>See our <a href="/community/">community</a> page for more details.</p> |
| </div> |
| <div class="col-md-8"> |
| <h1>Mesos Markdown Style Guide</h1> |
| |
| <p>This guide introduces a consistent documentation style to be used across the entire non-code documentation. |
| User guides and non-code technical documentation are stored in markdown files in the <code>docs/</code> folder. These files get rendered for the <a href="http://mesos.apache.org/documentation/latest/">online documentation</a>.</p> |
| |
| <p><strong>NOTE:</strong> As of right now this is work in progress and the existing documentation might not yet comply to this style.</p> |
| |
| <h2>What to Document?</h2> |
| |
| <p>Any new substantial feature should be documented in its own markdown file. |
| If the link between source code and documentation is not obvious, consider inserting a short code comment stating that there is non-code documentation that needs to be kept in sync and indicating where it is located.</p> |
| |
| <h2>Keep Documentation and Style Guides in Sync with Code.</h2> |
| |
| <p>When changing code consider whether you need to update the documentation. |
| This is especially relevant when introducing new or updating existing command line flags. |
| These should be reflected in <code>configuration.md</code>!</p> |
| |
| <h2>Section Headings</h2> |
| |
| <p>Use <a href="https://en.wikipedia.org/wiki/Capitalization#Title_case">title case</a> for |
| section headings, preferably the |
| <a href="http://blog.apastyle.org/apastyle/headings/">APA style</a> variant:</p> |
| |
| <ul> |
| <li>Capitalize the first word of any heading, including title, subtitle, |
| subheading.</li> |
| <li>Capitalize all “major” words (nouns, verbs, adjectives, adverbs, and pronouns) |
| in any heading, including the second part of hyphenated major words (e.g., |
| Self-Report not Self-report).</li> |
| <li>Capitalize all words of five letters or more.</li> |
| </ul> |
| |
| |
| <p>Effectively, only “minor” words of four letters or fewer, namely, conjunctions |
| (words like <strong>and</strong>, <strong>or</strong>, <strong>nor</strong>, and <strong>but</strong>), articles (the words <strong>a</strong>, |
| <strong>an</strong>, and <strong>the</strong>), and prepositions (words like <strong>as</strong>, <strong>at</strong>, <strong>by</strong>, |
| <strong>for</strong>, <strong>from</strong>, <strong>in</strong>, <strong>of</strong>, <strong>on</strong>, <strong>per</strong>, <strong>to</strong>, <strong>with</strong>), are |
| lowercased in any heading, as long as they aren’t the first word.</p> |
| |
| <h2>Code Examples</h2> |
| |
| <p>Code examples should be specified as follows:</p> |
| |
| <pre><code>~~~{.cpp} |
| int main(int argc, char** argv) |
| { |
| .... |
| } |
| ~~~ |
| </code></pre> |
| |
| <p><strong>NOTE:</strong> Because of shortcomings of Doxygen’s markdown parser we currently use indentation for wrapping all non C++ code blocks.</p> |
| |
| <h2>Notes/Emphasis</h2> |
| |
| <p>Notes are used to highlight important parts of the text and should be specified as follows.</p> |
| |
| <pre><code class="{.txt}">**NOTE:** Short note. |
| Continued longer note. |
| </code></pre> |
| |
| <p>We use single backticks to highlight individual words in a sentence such as certain identifiers:</p> |
| |
| <pre><code class="{.txt}">Use the default `HierarchicalDRF` allocator.... |
| </code></pre> |
| |
| <h2>Commands</h2> |
| |
| <p>We use single backticks to highlight sample commands as follows:</p> |
| |
| <pre><code class="{.txt}">`mesos-master --help` |
| </code></pre> |
| |
| <h2>Files/Paths</h2> |
| |
| <p>Files and path references should be specified as follows:</p> |
| |
| <pre><code class="{.txt}">Remember you can also use the `file:///path/to/file` or `/path/to/file` |
| </code></pre> |
| |
| <h2>Tables</h2> |
| |
| <p>In order to avoid problems with markdown formatting we should specify tables in html directly:</p> |
| |
| <pre><code><table class="table table-striped"> |
| <thead> |
| <tr> |
| <th width="30%"> |
| Flag |
| </th> |
| <th> |
| Explanation |
| </th> |
| </thead> |
| <tr> |
| <td> |
| --ip=VALUE |
| </td> |
| <td> |
| IP address to listen on |
| </td> |
| </tr> |
| <tr> |
| <td> |
| --[no-]help |
| </td> |
| <td> |
| Prints this help message (default: false) |
| </td> |
| </tr> |
| </table> |
| </code></pre> |
| |
| <h2>Indentation and Whitespace</h2> |
| |
| <p>We use no extra indentation in markdown files. |
| We have one new line after section headings and two blank lines |
| in between sections.</p> |
| |
| <pre><code class="{.txt}">... end of previous section. |
| |
| |
| ## New Section |
| |
| Beginning of new section .... |
| </code></pre> |
| |
| </div> |
| </div> |
| |
| </div><!-- /.container --> |
| </div><!-- /.content --> |
| |
| <hr> |
| |
| |
| |
| <!-- footer --> |
| <div class="footer"> |
| <div class="container"> |
| <div class="col-md-4 social-blk"> |
| <span class="social"> |
| <a href="https://twitter.com/ApacheMesos" |
| class="twitter-follow-button" |
| data-show-count="false" data-size="large">Follow @ApacheMesos</a> |
| <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> |
| <a href="https://twitter.com/intent/tweet?button_hashtag=mesos" |
| class="twitter-hashtag-button" |
| data-size="large" |
| data-related="ApacheMesos">Tweet #mesos</a> |
| <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> |
| </span> |
| </div> |
| |
| <div class="col-md-8 trademark"> |
| <p>© 2012-2017 <a href="http://apache.org">The Apache Software Foundation</a>. |
| Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation. |
| <p> |
| </div> |
| </div><!-- /.container --> |
| </div><!-- /.footer --> |
| |
| <!-- JS --> |
| <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script> |
| <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script> |
| </body> |
| </html> |