User's Guide instead of manual

Author: rhornig

Diff for: DocumentationGuidelines.md

@@ -6,7 +6,8 @@ underMenu: Development
 
 We maintain documentation in the following forms:
 
-*   **INET Framework Manual** is meant to provide an overview about the components and architecture of the framework
+*   **INET Framework User's Guide** is meant to provide information for users who want to assemble new models from pre-existing components. It provides an overview of the components and architecture of the framework.
+<!-- *   **INET Framework Developer's Guide** is meant to provide information for the developers who intend to extend INET with new components, written in C++. -->
 *   **INET Reference**, built from NED and C++ source, provides cross-linked, browsable reference information about the modules and classes of the implementation
 
 The following auxiliary files are managed by the core INET maintainers:
@@ -15,22 +16,22 @@ The following auxiliary files are managed by the core INET maintainers:
 *   **WHATSNEW** (in the project root directory) is updated before each release, and contains a summary of changes in the whole framework.
 *   **AUTHORS** (in the project root directory) records the names of those who contributed to the project. The [Contributors](/Contributors.html) page should always contain a mirror of this file.
 
-## The Manual
+## The User's Guide
 
 Technically:
 
-*   Sources are in the repository under [doc/src/manual][2], in LaTeX.
+*   Sources are in the repository under [doc/src/users-guide][2], in LaTeX.
 *   PDF and/or HTML built by the release manager for each release
 
 Content and level of details:
 
-*   The purpose of the Manual is to provide introductory and overview information for newcomers, and give a high-level overview of the architecture and important internal APIs for contributors.
-*   High-level information about every implemented protocol model or component, potentially including practical advice on how to use them or combine them with other models
-*   High-level overview of internal interfaces, such as cross-layer communication
+*   The purpose of the User's Guide is to provide introductory and overview information for newcomers, and give a high-level overview of the architecture and configuration options.
+*   High-level information about every implemented protocol model or component, potentially including practical advice on how to use them or combine them with other models.
 
 However, it should not:
 
 *   Be as detailed as to duplicate information in the Reference
+*   Describe internal interfaces that are used by C++ code.
 *   Attempt to teach or describe the protocol itself (that's not the job of the manual)
 
 ## The Reference

Diff for: Manual.md

@@ -0,0 +1,15 @@
+---
+layout: page
+title: User's Guide
+underMenu: Documentation
+---
+
+The User's Guide is currently in preparation. It provides an overview of the concepts, architecture, and main
+components of the INET Framework, and it is meant to be used with the Reference.
+
+You can read the current version of the User's Guide [here][4].
+
+Helping hands on the INET documentation would be very much appreciated. More info [here][3].
+
+ [3]: DocumentationGuidelines.html
+ [4]: https://omnetpp.org/doc/inet/api-current/inet-users-guide.pdf

Diff for: UsersGuide.md

@@ -19,9 +19,9 @@
     - name: Model Catalog
       link: /Protocols.html
     - name: INET Reference
-      link: http://omnetpp.org/doc/inet/api-current
-    - name: INET Manual
-      link: /Manual.html
+      link: https://omnetpp.org/doc/inet/api-current
+    - name: INET User's Guide
+      link: /userguide/inet-users-guide.html
     - separator: true
     - name: 3rd Party Tutorials
       link: /Tutorials.html

Diff for: _data/menu.yml

@@ -6,6 +6,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <link rel="stylesheet" href="/stylesheets/bootstrap-cerulean.min.css" media="screen">
     <link rel="stylesheet" href="/stylesheets/inet.css">
+    <link rel="stylesheet" href="{{site.baseurl}}/stylesheets/rainbow.css">
     <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
     <!--[if lt IE 9]>
       <script src="javascripts/html5shiv.js"></script>
@@ -41,6 +42,16 @@
       ul.nav li.dropdown:hover ul.dropdown-menu { display: block; }  /* open menus on hover */
       .navbar { border-bottom: 4px solid #ff8800; }  /* minimal styling: orange strip under navbar */
       .frontpage h3 { border-bottom: 4px solid #ff8800; padding-bottom: 3px; }
+
+      table.matrix { display:inline-block; vertical-align: middle; position: relative; border: 0px; background:#ffffff; margin-left:8pt; margin-right:8pt; }
+      table.matrix:before, table.matrix:after { content: ""; position: absolute; top: 0; border: 1px solid #000; width: 6px; height: 100%; }
+      table.matrix:before { left: -6px; border-right: 0px; }
+      table.matrix:after { right: -6px; border-left: 0px; }
+      table.matrix td { padding: 5px; text-align: center; border: 0px; }
+
+      a.headerlink { visibility: hidden; font-size: 0.8em; padding: 0 4px 0 4px; text-decoration: none; color: #82A3AF; }
+      h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, h4:hover > a.headerlink { visibility: visible; }
+
     </style>
   </head>
   <body {% if page.generateToC %}onload="generateToC();"  data-spy="scroll" data-target=".bs-docs-sidebar"{% endif %}{% if page.frontpage %} class="frontpage"{% endif %}>
@@ -113,6 +124,11 @@
     <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
     <script src="/javascripts/bootstrap.min.js"></script>
     <script src="/javascripts/cerulean.js"></script>
+    <script src="{{site.baseurl}}/javascripts/quoting.js"></script>
+    <script src="{{site.baseurl}}/javascripts/rainbow-custom.min.js"></script>
+    <script src="{{site.baseurl}}/javascripts/rainbow-ned.js"></script>
+    <script src="{{site.baseurl}}/javascripts/rainbow-ini.js"></script>
+    <script src="{{site.baseurl}}/javascripts/rainbow-html.js"></script>
   </body>
 </html>
 

Diff for: _layouts/default.html

@@ -0,0 +1,96 @@
+//
+// Allows including a line range of a file from HTML. Example:
+//
+// <pre src="../WirelessA.ned" from="network WirelessA" until="####"></pre>
+//
+// "from", "until" are regexes that match substring of a line; "from" is inclusive, "until" is exclusive
+//
+// Returns an object/dictionary/map with two values:
+//   startLine - the line number where the returned snippet begins in the whole text (starting from 1 as usual...)
+//   snippet   - the actual matched snippet text
+var getLines = function(text, after, from, until, upto, comment) {
+
+    let startPattern = from == null ? after : from;
+    let isStartInclusive = from != null;
+
+    let endPattern = until == null ? upto : until;
+    let isEndInclusive = upto != null;
+
+    if (startPattern == null) {
+        startPattern = "";
+        isStartInclusive = true;
+    }
+
+    if (endPattern == null) {
+        endPattern = "[\\s\\S]*";
+        isEndInclusive = true;
+    }
+
+    let re = new RegExp("([\\s\\S]*?)(^.*" + startPattern + ".*$\\n)([\\s\\S]*?)(^.*" + endPattern + ".*$)", "m");
+
+    let matches = text.match(re);
+
+    // Group 1 is the "preface" - everything before the snippet.
+    // Group 2 is the lines enclosing the start marker
+    // Group 3 is the snippet "body"
+    // Group 4 is the lines enclosing the end marker
+    if (matches == null)
+        return { startLine: 0, snippet: "!!! No matching lines !!!" };
+
+    let preface = isStartInclusive ? matches[1] : (matches[1] + matches[2]);
+    let snippet = (isStartInclusive ? matches[2] : "")
+                    + matches[3]
+                    + (isEndInclusive ? matches[4] : "");
+
+    startLine = preface.split('\n').length;
+
+    // trimming trailing whitespace (empty lines)
+    snippet = snippet.replace(/\s+$/, '');
+
+    if (comment) // [^\S\n] character class is a "double-negative": matches any whitespace, except a newline
+        snippet = snippet.replace(new RegExp("[^\\S\\n]*" + comment + ".*$", "mg"), '');
+
+    return { startLine: startLine, snippet: snippet };
+}
+
+var fileLoaded = function(file, data) {
+   pres = $('pre[src="' + file + '"]');
+   $.each(pres, function(i,pre) {
+      pre.textContent = "";
+      excerpt = getLines(data,
+                         pre.attributes.after ? pre.attributes.after.value : null,
+                         pre.attributes.from ? pre.attributes.from.value : null,
+                         pre.attributes.until ? pre.attributes.until.value : null,
+                         pre.attributes.upto ? pre.attributes.upto.value : null,
+                         pre.attributes.comment ? pre.attributes.comment.value : null);
+
+      var language = file.endsWith(".ned") ? "ned" : file.endsWith(".xml") ? "xml"
+          : file.endsWith(".ini") ? "ini" : file.endsWith(".py") ? "python"
+          : file.endsWith("Dockerfile") ? "dockerfile" : "generic";
+
+      // this new element will hold some attributes to aid Rainbow and Rainbow.linenumbers, as well as the snippet content.
+      var codeElement = document.createElement('code');
+      codeElement.setAttribute('display', 'none'); // so it won't appear unformatted
+      codeElement.setAttribute('data-language', language); // used by Rainbow
+      codeElement.setAttribute('data-line', excerpt.startLine); // used by Rainbow.linenumbers
+      $(codeElement).text(excerpt.snippet); // making sure we escape it
+      pre.appendChild(codeElement); // adding the <code> to the DOM
+
+      // And then invoke the highlighter on the containing <pre>.
+      // The Rainbow.linenumbers plugin will replace the <code> with a <table>.
+      Rainbow.color(pre);
+   });
+};
+
+document.addEventListener("DOMContentLoaded", function (event) {
+   pres = $('pre[src]');
+   files = new Set();
+   $.each(pres, function(i,pre) {pre.textContent="Loading...\n"; files.add(pre.attributes.src.value); });
+
+
+   files.forEach(function(file) {
+      jQuery.ajax({url: file,
+                   success: function(data) { fileLoaded(file, data); },
+                   dataType: "text" });
+   });
+});

Diff for: javascripts/quoting.js

@@ -0,0 +1,135 @@
+/**
+ * HTML patterns
+ *
+ * @author Craig Campbell
+ */
+Rainbow.extend('html', [
+    {
+        name: 'source.php.embedded',
+        matches: {
+            1: 'variable.language.php-tag',
+            2: {
+                language: 'php'
+            },
+            3: 'variable.language.php-tag'
+        },
+        pattern: /(<\?php|<\?=?(?!xml))([\s\S]*?)(\?>)/gm
+    },
+    {
+        name: 'source.css.embedded',
+        matches: {
+            1: {
+                matches: {
+                    1: 'support.tag.style',
+                    2: [
+                        {
+                            name: 'entity.tag.style',
+                            pattern: /^style/g
+                        },
+                        {
+                            name: 'string',
+                            pattern: /('|")(.*?)(\1)/g
+                        },
+                        {
+                            name: 'entity.tag.style.attribute',
+                            pattern: /(\w+)/g
+                        }
+                    ],
+                    3: 'support.tag.style'
+                },
+                pattern: /(<\/?)(style.*?)(>)/g
+            },
+            2: {
+                language: 'css'
+            },
+            3: 'support.tag.style',
+            4: 'entity.tag.style',
+            5: 'support.tag.style'
+        },
+        pattern: /(<style.*?>)([\s\S]*?)(<\/)(style)(>)/gm
+    },
+    {
+        name: 'source.js.embedded',
+        matches: {
+            1: {
+                matches: {
+                    1: 'support.tag.script',
+                    2: [
+                        {
+                            name: 'entity.tag.script',
+                            pattern: /^script/g
+                        },
+
+                        {
+                            name: 'string',
+                            pattern: /('|")(.*?)(\1)/g
+                        },
+                        {
+                            name: 'entity.tag.script.attribute',
+                            pattern: /(\w+)/g
+                        }
+                    ],
+                    3: 'support.tag.script'
+                },
+                pattern: /(<\/?)(script.*?)(>)/g
+            },
+            2: {
+                language: 'javascript'
+            },
+            3: 'support.tag.script',
+            4: 'entity.tag.script',
+            5: 'support.tag.script'
+        },
+        pattern: /(<script(?! src).*?>)([\s\S]*?)(<\/)(script)(>)/gm
+    },
+    {
+        name: 'comment.html',
+        pattern: /<\!--[\S\s]*?-->/g
+    },
+    {
+        matches: {
+            1: 'support.tag.opening',
+            2: 'support.tag.closing'
+        },
+        pattern: /(<)|(\/?\??>)/g
+    },
+    {
+        name: 'support.tag',
+        matches: {
+            1: 'support.tag',
+            2: 'support.tag.special',
+            3: 'support.tag-name'
+        },
+        pattern: /(<\??)(\/|\!?)(\w+)/g
+    },
+    {
+        matches: {
+            1: 'support.attribute'
+        },
+        pattern: /([a-z-]+)(?=\=)/gi
+    },
+    {
+        matches: {
+            1: 'support.operator',
+            2: 'string.quote',
+            3: 'string.value',
+            4: 'string.quote'
+        },
+        pattern: /(=)('|")(.*?)(\2)/g
+    },
+    {
+        matches: {
+            1: 'support.operator',
+            2: 'support.value'
+        },
+        pattern: /(=)([a-zA-Z\-0-9]*)\b/g
+    },
+    {
+        matches: {
+            1: 'support.attribute'
+        },
+        pattern: /\s([\w-]+)(?=\s|>)(?![\s\S]*<)/g
+    }
+]);
+
+Rainbow.addAlias('xml', 'html');