Sentinel Collector SDK 2014 Updates: Collector Documentation

over 6 years ago
This article is part of a series of articles diving into the new functionality present in the 2014 Preview Sentinel SDK. Today I will be covering the new documentation options and what they mean for those who have developed collectors previously, as well as all of us developing collectors now and in the future. As in other articles, it may be useful to dive into some of the history of the SDK to lead into where we are going in the future, and provide some of the rationale behind that map.

The Sentinel SDK has been available to the public for many years, and has been evolving during that time to simplify the setup, provide additional capabilities to developers, and generally improve the base/boilerplate code that powers all of the plugins within Sentinel based on customer feedback; the 2011.1 SDK beta a few years ago had a lot of big changes to make the SDK setup a simple process that anybody can do instead of ten pages of steps. The documentation for collector plugins has existed throughout this time, and the format of the documentation has always been a template file provided by default when the collector plugin was started in the SDK, with some fields being pulled in from other parts of the collector at build time. Perhaps an example will help explain this.

In the 2011.1, as well as the 2014 Preview, SDK when building a new collector plugin there is a release.odt file which is a stock file with generic information that applies to collectors in general. This is editable using a proper document editor (LibreOffice, OpenOffice, or anything else supporting the public OpenDocument format) to add specific information for the current collector plugin. There are also document variables contained within this file which are automatically filled-in whenever the document is built; for example:

@AUTHOR@ - Replaced with the plugin's author
@PLUGIN@ - Replaced with the name of the plugin.
@UUID@ - Replaced with the plugin's UUID

During the build process for a collector there used to be a prompt that would ask something along the lines of, "Do you want to build documentation?" If you chose 'yes', and if you had your system configured properly (LibreOffice or OpenOffice installed, and referenced within the SDK plugin) the build process would use the release.odt file, plus a bunch of settings from the collector plugin that was being developed, and merge everything into a nice single document on the fly, creating a PDF and embedding it where necessary. The result is that a Production build of the collector automatically had (as much as possible) up-to-date information on the collector itself; connection methods were in there and updated, names of plugins, authors, vendors, your customized description of the plugin updated five minutes go per the customer's request, etc. For more details on how things used to be, see the Plug-In Documentation page found at of the SDK web-based documentation. Because this process called an external process and then did a lot of mangling of information in release.odt within the document, it was a bit slow compared to the rest of the build process. Also, the PDF that was built was stored along with the collector, but usually has not been the one available within the plugin, and therefore accessible to a Sentinel user within ESM who was given a different version of mostly-boilerplate information. Finally, PDF is a great format, but it requires a special client of some sort to read it, where other formats can be read by just about anything. This all leads up to changes in the latest SDK.

Today all of that is still present, but you do not need it anymore. If you want to use it, particularly if you are upgrading to using the 2014 Preview SDK with a collector plugin created from a previous version of the SDK which already has documentation that you are not yet ready to recreate, you can enable building of the old style of documentation by modifying ~/.netiq/pluginsdk/ as the build output states:


[echo] External PDF will not be created because the variable build.pdf
in ~/.netiq/pluginsdk/ has been set to no.

Looking in the file mentioned the option to enable this setting, or prompt for it, or specify an alternate path for soffice, is all pretty obvious:


Now that we know how to do the old way if needed, let's talk about the new way. My opinion of the drawbacks to be overcome with the old way were requirements for external software (LibreOffice/OpenOffice), slowness, inconsistent documentation within the plugin vs. what was distributed separately, and limitations around the formats used (PDF in particular). Keeping in mind the need to keep everything properly cross-platform, the only options for some sort of document template and merge system other than the LibreOffice/OpenOffice format would be something like HTML which can be rich in nature but is completely able to be hacked with standard markup tools (WYSIWYG editors, text editors, XSLT and XML tools, etc.). Removing this dependency also removes some slowness due to lighter-weight applications being loaded, and the removal of the PDF format. As long as the documentation that was built was placed both inside the plugin as well as alongside it in the build directory, all problems are solved. Tada, here we are today.

The new way, using HTML as the final format, should be accessible anywhere... mobile phone, dedicated monitoring system, laptop, tablet; really what cannot open and render HTML pretty well these days? There was a potential downside to HTML in my mind, and that was the traditional use of dozens of files to support a single final product. For example, look at how many HTTP request are made by your web browser the next time you hit a website, and you'll see that there are images, CSS files, JS files, etc. all being roped in to make the final display what the author expects. While CSS and JS are regularly embedded, what about images? It turns out that while images are being avoided generally (big, harder to render on smaller screens, overused and providing a disproportionately small amount of value compared to size and other downsides) it is possible to embed an image entirely in HTML, so this was good news for me. Since it is useful information generally, let's start there.

For a quick read on the topic outside of the Sentinel world, check out this link from StackOverflow: (Embedding Base64 Images) The technology is known as Data URIs, is described on Wikipedia with some quick details including browser compatibility and solves our problem nicely. There are some good reasons to NOT use these in normal web-based content, but this is neither normal nor web-based, so we'll make an exception. Note that adding images or other heavy content to a page will make it load more-slowly, as always, no matter how it is roped in for use in the client.

The basic look of the <img/> tag changes from something like this:

<img src="path/to/image.png"/>

to this:
<img src="alt="Embedded Image" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA/MAAABN"/>

Note that the src field includes the string 'data:', a colon (:), a MIME type (image/png), semicolon (;), a format (base64), one more comma (,), and then the base64-encoded image (obviously truncated here for brevity). The end result when putting these images somewhere in the HTML file is you end up with long lines of base64-encoded data, but it makes something otherwise impossible able to be done pretty easily. As an example, pretend you have decided to include a screenshot of the application vendor's logo, or maybe your customer's/employer's logo, and you want that somewhere in the final documentation to provide something extra and personalized. The first step is to get the image, if not available already, into a format that is made for the web; Portable Network Graphics (PNG) format is a good option, as is Scalar Vector Graphics (SVG), or maybe Joint Photographic Experts Group (JPEG). Once the file is available the next step is to base64-encode it and determine the proper MIME designation (image/png, image/svg xml, or image/jpeg). Base64-encoding is trivial most of the time, and can be done using something like the following on any old server you have:

base64 /path/to/image/file.png | tr -d '\n'

The line above uses the built-in base64 command, giving it a file to encode, and then strips out newlines in the resulting output so only one big long string of base64-encoded data remains. The reason for the newlines is mostly convention; it is common for encodings like base64 to be "folded" after so many characters (78 usually) to fit within the size of an old-fashioned terminal window nicely, and to avoid pain and suffering in today's powerful editors that will otherwise try to show you the millionth character in a megabyte-long string of data. Still, for our purposes with data URIs we want one big long string of stuff, so we send the encoded data through 'tr' telling it to delete newlines, and now we're ready.

To provide a workable example with a known file, let's take SUSE's logo from Wikipedia: Pull down the file, encode it as shown above (or with another base64-encoding mechanism of your choosing) and then create the data URI that results:

curl -O
base64 Suse_logo_w-tag_color.png | tr -d '\n'

The resulting data URI should look like this:

<img src="alt="SUSE Logo Embedded Image" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAANwAAAB7CAYAAAAfQ 7XAAAACXBIWXMAAC4jAAAuIwF4pT92AAAKT2lDQ1BQaG90b3Nob3AgSUNDIHByb2ZpbGUAAHjanVNnVFPpFj333vRCS4iAlEtvUhUIIFJCi4AUkSYqIQkQSoghodkVUcERRUUEG8igiAOOjoCMFVEsDIoK2AfkIaKOg6OIisr74Xuja9a89 bN/rXXPues852zzwfACAyWSDNRNYAMqUIeEeCDx8TG4eQuQIEKJHAAEAizZCFz/SMBAPh PDwrIsAHvgABeNMLCADATZvAMByH/w/qQplcAYCEAcB0kThLCIAUAEB6jkKmAEBGAYCdmCZTAKAEAGDLY2LjAFAtAGAnf bTAICd Jl7AQBblCEVAaCRACATZYhEAGg7AKzPVopFAFgwABRmS8Q5ANgtADBJV2ZIALC3AMDOEAuyAAgMADBRiIUpAAR7AGDIIyN4AISZABRG8lc88SuuEOcqAAB4mbI8uSQ5RYFbCC1xB1dXLh4ozkkXKxQ2YQJhmkAuwnmZGTKBNA/g88wAAKCRFRHgg/P9eM4Ors7ONo62Dl8t6r8G/yJiYuP 5c rcEAAAOF0ftH LC zGoA7BoBt/qIl7gRoXgugdfeLZrIPQLUAoOnaV/Nw H48PEWhkLnZ2eXk5NhKxEJbYcpXff5nwl/AV/1s X48/Pf14L7iJIEyXYFHBPjgwsz0TKUcz5IJhGLc5o9H/LcL//wd0yLESWK5WCoU41EScY5EmozzMqUiiUKSKcUl0v9k4t8s wM 3zUAsGo AXuRLahdYwP2SycQWHTA4vcAAPK7b8HUKAgDgGiD4c93/ 8//UegJQCAZkmScQAAXkQkLlTKsz/HCAAARKCBKrBBG/TBGCzABhzBBdzBC/xgNoRCJMTCQhBCCmSAHHJgKayCQiiGzbAdKmAv1EAdNMBRaIaTcA4uwlW4Dj1wD/phCJ7BKLyBCQRByAgTYSHaiAFiilgjjggXmYX4IcFIBBKLJCDJiBRRIkuRNUgxUopUIFVIHfI9cgI5h1xGupE7yAAygvyGvEcxlIGyUT3UDLVDuag3GoRGogvQZHQxmo8WoJvQcrQaPYw2oefQq2gP2o8 Q8cwwOgYBzPEbDAuxsNCsTgsCZNjy7EirAyrxhqwVqwDu4n1Y8 xdwQSgUXACTYEd0IgYR5BSFhMWE7YSKggHCQ0EdoJNwkDhFHCJyKTqEu0JroR cQYYjIxh1hILCPWEo8TLxB7iEPENyQSiUMyJ7mQAkmxpFTSEtJG0m5SI ksqZs0SBojk8naZGuyBzmULCAryIXkneTD5DPkG Qh8lsKnWJAcaT4U IoUspqShnlEOU05QZlmDJBVaOaUt2ooVQRNY9aQq2htlKvUYeoEzR1mjnNgxZJS6WtopXTGmgXaPdpr h0uhHdlR5Ol9BX0svpR iX6AP0dwwNhhWDx4hnKBmbGAcYZxl3GK YTKYZ04sZx1QwNzHrmOeZD5lvVVgqtip8FZHKCpVKlSaVGyovVKmqpqreqgtV81XLVI pXlN9rkZVM1PjqQnUlqtVqp1Q61MbU2epO6iHqmeob1Q/pH5Z/YkGWcNMw09DpFGgsV/jvMYgC2MZs3gsIWsNq4Z1gTXEJrHN2Xx2KruY/R27iz2qqaE5QzNKM1ezUvOUZj8H45hx Jx0TgnnKKeX836K3hTvKeIpG6Y0TLkxZVxrqpaXllirSKtRq0frvTau7aedpr1Fu1n7gQ5Bx0onXCdHZ4/OBZ3nU9lT3acKpxZNPTr1ri6qa6UbobtEd79up 6Ynr5egJ5Mb6feeb3n hx9L/1U/W36p/VHDFgGswwkBtsMzhg8xTVxbzwdL8fb8VFDXcNAQ6VhlWGX4YSRudE8o9VGjUYPjGnGXOMk423GbcajJgYmISZLTepN7ppSTbmmKaY7TDtMx83MzaLN1pk1mz0x1zLnm eb15vft2BaeFostqi2uGVJsuRaplnutrxuhVo5WaVYVVpds0atna0l1rutu6cRp7lOk06rntZnw7Dxtsm2qbcZsOXYBtuutm22fWFnYhdnt8Wuw 6TvZN9un2N/T0HDYfZDqsdWh1 c7RyFDpWOt6azpzuP33F9JbpL2dYzxDP2DPjthPLKcRpnVOb00dnF2e5c4PziIuJS4LLLpc Lpsbxt3IveRKdPVxXeF60vWdm7Obwu2o26/uNu5p7ofcn8w0nymeWTNz0MPIQ BR5dE/C5 VMGvfrH5PQ0 BZ7XnIy9jL5FXrdewt6V3qvdh7xc 9j5yn M 4zw33jLeWV/MN8C3yLfLT8Nvnl F30N/I/9k/3r/0QCngCUBZwOJgUGBWwL7 Hp8Ib OPzrbZfay2e1BjKC5QRVBj4KtguXBrSFoyOyQrSH355jOkc5pDoVQfujW0Adh5mGLw34MJ4WHhVeGP45wiFga0TGXNXfR3ENz30T6RJZE3ptnMU85ry1KNSo qi5qPNo3ujS6P8YuZlnM1VidWElsSxw5LiquNm5svt/87fOH4p3iC N7F5gvyF1weaHOwvSFpxapLhIsOpZATIhOOJTwQRAqqBaMJfITdyWOCnnCHcJnIi/RNtGI2ENcKh5O8kgqTXqS7JG8NXkkxTOlLOW5hCepkLxMDUzdmzqeFpp2IG0yPTq9MYOSkZBxQqohTZO2Z pn5mZ2y6xlhbL xW6Lty8elQfJa7OQrAVZLQq2QqboVFoo1yoHsmdlV2a/zYnKOZarnivN7cyzytuQN5zvn//tEsIS4ZK2pYZLVy0dWOa9rGo5sjxxedsK4xUFK4ZWBqw8uIq2Km3VT6vtV5eufr0mek1rgV7ByoLBtQFr6wtVCuWFfevc1 1dT1gvWd 1YfqGnRs FYmKrhTbF5cVf9go3HjlG4dvyr Z3JS0qavEuWTPZtJm6ebeLZ5bDpaql aXDm4N2dq0Dd9WtO319kXbL5fNKNu7g7ZDuaO/PLi8ZafJzs07P1SkVPRU lQ27tLdtWHX G7R7ht7vPY07NXbW7z3/T7JvttVAVVN1WbVZftJ 7P3P66Jqun4lvttXa1ObXHtxwPSA/0HIw6217nU1R3SPVRSj9Yr60cOxx  /p3vdy0NNg1VjZzG4iNwRHnk6fcJ3/ceDTradox7rOEH0x92HWcdL2pCmvKaRptTmvtbYlu6T8w 0dbq3nr8R9sfD5w0PFl5SvNUyWna6YLTk2fyz4ydlZ19fi753GDborZ752PO32oPb  6EHTh0kX/i c7vDvOXPK4dPKy2 UTV7hXmq86X23qdOo8/pPTT8e7nLuarrlca7nuer21e2b36RueN87d9L158Rb/1tWeOT3dvfN6b/fF9/XfFt1 cif9zsu72Xcn7q28T7xf9EDtQdlD3YfVP1v 3Njv3H9qwHeg89HcR/cGhYPP/pH1jw9DBY Zj8uGDYbrnjg OTniP3L96fynQ89kzyaeF/6i/suuFxYvfvjV69fO0ZjRoZfyl5O/bXyl/erA6xmv28bCxh6 yXgzMV70VvvtwXfcdx3vo98PT R8IH8o/2j5sfVT0Kf7kxmTk/8EA5jz/GMzLdsAAAAgY0hSTQAAeiUAAICDAAD5/wAAgOkAAHUwAADqYAAAOpgAABdvkl/FRgAAJABJREFUeNrsnXeYVOXZxn9n2u6yu0jRRQFBNNh7L9EINtBYEzX5rJEkVtRYkxi/qEFJ TSJSWyoxIKooILSFAVB tLr0mGXLZRley/z/fE84x5mp5yZnZmd3T33dZ1rYebMmTPvee/3Ke9TjN/PGUoHRk9gIDAAOEKPPkAvPTKAdCAN8Aa5RhXQCNToUQ6UAiXALtNRCOTrezbaAQ6nwWu3LmLfjqoO xtcHex jwFOAM4EztD/H6ykiieagUqgGNgJrAPW698tSkSrSAHGAD2AtcAmYDOwQ0ndbFOr8yLZCXcQcBpwOXAxcKxKtYQvrkB3PQbpvfhQoCTMBhYBK4GtQH2Qaxn6m04ErtbXmoDdKknXA8v0Otv0 jZswsUNGcC5wA06sY9L8jHsq8d5wIOqouYoAecAi1V6eU3SssHvGk7Tdc4G7tTXd6kEXKpkXqav2VLQJlybcRzwU B6lQAdFemq7p4B3KO24HJgFjBTpVaqxWv118NnaO9XyTcPmKtELLOnsU24SFS1S4G7gCuBzE44xj2BS/T4o9ptfaO8Vi8l31CVmJtVik4BvkUcPjZswrWCB7gOuFvVRkcXGW8PcHqMrmUAR vxK1U9JwEfAivsqZ2cSPRETwHuAL4DPtKV2mE/hpjgaOAJ09iebw9J15VwTnWCPKIOERttxx5kW6JQ7cbByDZJOnCTahBvAE8C1fZwdR3CDQF r7aajbYjF3hR1cdcP3X1POAhxPHkAR5AggJuQfYROyy8XnB5HBgOw1Ypg2AQ8DrwpU22mGGOquEvK9kGAheqXejQ929Q0vm2Hq4BRnf0H 5OcZC7qpSq4jqbcAEcA/cDs4FfA26bJzHBOlUVtyIBAB8g2w3fAPOR/b779NyXgT YPnsPcEGHJlyqk6JNFVSXNdgqpQmnAH8DLrP5EVM0AY q3XYG8BlwuHk AicD/1EyPqTPYZiq9C79/AKCx5Qmgd4ITo8Dh tAtdEADAOKczu KeqK4XUeVVutu82PmGOuquapwCt ZFuq2kQv4CfASCTK5T3gH0o4kH3Ok4DVSTsZUxyU7a6lrKj2QMI5DBpqm1g Kd8mHPADfbBX2byIG2bo34uR0C8fJgM3Az7D5lUl50jgff13nhI0BbgNeDwpbRunQX1NE /cu5TSwtpO yDbasMNA76yyRZ3bNe/Z/m9XmUiG0CFqp9HIWlKpRzoybyWZIzm8UJKuouVUwo6NdnaKuEeBZ7XldNGfNGof/3H n QNJ/pQBZwqxKqmBZnVZPp/MHAD/X85Fn13QalhbVkT8zr9A/SFeVnXlK1xUZikKV/A9lfV phRhGwVwl6sN97NyQb4dK6e/joiVWdwikSa5WyG/COTbaE40L9 w2S6hMOE4Ba4Hi1sc24VKVi 2uSXkhNd5E9MY/tS/d3iQcZCeEykL2f/7Hnf0zxLTA1zDlXKnGKVZVvCnHuAtVAQLIwPH7vDyBJwuvSMl1sWVTM5OfW0ljXbBPOhEzE63WtzY Y4wjgXiQMqzDIOT2BF/TfnyJ5g6s4cE tBnhXVcYKJHj5ziDP/PL2/tGGw6CqpJ7v/rsdr7frPGwrhPMAr9lkiyvhrkc2rS9WlT3Qcn8j8Jz exJwEfBjJMt8hBLsDqRUwwl6nYwg33mZmgfthvQeHhaM29llVMlICPc3W42MO0bowrZJpdJwJEPcH08D49U2KwemAf8C3kYywd3IXtuXAWw3Mw5rLzvOneokrbubdV8XkT0hr8s9aCNMmbz7gX/bfEgIbgQmmv7vVMn3EOLKN6MM2f cj9Q46aYkHAacGuZ7tqpUnJY474i4/j1pLvJWlbBg3E5y5uylqaHZJpwJF pDTbW5kBDsAf4JvKn//l4oqM31a8TDGK0qWKPXHuV3/firUU6Din31zHx5Extm7 5SNptVlTJLH45NtsQhCwkkWIzUPhmorzcgXsxrdREcjdRFqbd43RLgv/rZBxNNNoDU7i5yZu9h/ayuTTYIvvH9PJKyb6N9nCjPIJ7LicA4YKG t1yPUUjWwPn690hkgzsNCfXaA2xEqnt9jRQb8mEIUgnsvUT8GKfbQU1pA1sW77OfbBCV8irgc xaI8mCeiXNh oMCSShUlXV9KhErEI2vs04D/glcDswVlXUuNptKRku6mua OjxlWxZVGw/yQASLkOlm0225IGHlvCtXUhY1hQkLcdXlbk2AMFAapxcpA6Zi2iJxZwa75tOyXCRt7qUOW9us8kWgnB3I0mk0aKClji UlnncKm600vtlHR72KNGf6Qk3q QfgarVcXcoLZaCuLyP1Gf43G0Lg2fh6TtxEFfApfbQWqmm WT8vnk6dVd3mYLRbg wG iuEYJkq81FYl yKV1QVIX0iegP K vhTZfD3cfgRRo58ewyP4TBPwrD6z2E4kjwOn20HhxnIWjtvJmi LbLKFIdyd gCtohYpEvS6rrCh0IjEARYrKcertBsO/AL4kf0o4o5sZOP8y1gTzeEy2L25koUf7GT1tEKam22mhSNcdyTQ1SpWIBkD89vw3XuQ8KNxiMv7d4jHzUZssRgJzZugzpSYOETcqQ4cTgdFmyvI/iSPlVMKukwAciwINxzr2wBfIYmOe2N0D43AJ7ryPooULk2zH02bUIWEho1VJ0vM0qjdKU6cHgeFOWUs/SSfVdMLqK9uskc8QsLdbPH8OUiptlAdW45To/1w4BAkwmEP0rhwA8GbF1aqfTEPCSc71n48EWE3sEbt6elIn7mYqo7uVCeFOeUs jCXtTOLbKJFSbi tI7VC4RcJBo9ENlSgZ rWnoqwaPU85F8rfeQWL5AT wbpNjpe0jHmc6ASv1dK5CWUw4doyy1mw9FnFbdVbqn0dqD7EU2tWtUgu1G4iJXI4HL67CWnBoRHC4Dj9aEXDg lzUzCmmst1XHthDudFqn4QfQ2nkS6fTpjzNUIllJauyH7AndqBPwGZVo/ihESr6NRQJ4OzKWINstK8Ocd5AePfRvBhLA7EVKM9YqcUv02Ec8GzMakJbppiS/hqlv5LB6WgFNjbYzJFaEC1ewfQbSkcUfQ9XpcWgU330JcI6S7sUA75epRDWQxhSxxFpkL2qVaeI6kT2rI5D6jWcQmdc2EIqQuv5bLJxbpkduu84ILcaK18vKKQUs/GAnBRvstnOxJFy4lr5NSN1J/ XtJKTkQp82fH8G8H86sR8LsGJXINsGWcSm/dJmJDD4c8J77HzbFncjYVHR4AOLZEsKGAZ40l0U51Yz8anVNtHiAAfhN5830DoywYWkkvSJ0X38BvhTkPdKkaTKXW38jnkqkcdjzT3u27YYgtTsj3Sz2IvUK kYZHMYpGS4 OaVLbw5YolNtjgSLivMOXNp7Vb21awPhn062SYj7mkratLv1bYLhG066aO1WXYiWevRkLYOqWg8PEKnRC3BPbLJA690pknr7ubLv29i7tvbqC6pt5kRR8KF6wUQqBbiz4Kc2wz8VW2zIWp7XYJUDP4p0p0zFP4SYgH4Aqn7EQ2eRWII24LF6sjZHYGEa052sqVkuijcVMG79y9j/ns7bEYkgHDh4K9KpRG8T/VfEW/mtgDq2ScqGV8M8V2D1GYKhj8hrvBIsBWpdBULLEcibKxsQKUi 5DtqCeq/u9xkJrpwtPNecDrKRkuinIqGP/oSjbN22uzIUGEC eh9HeW9KZ1BDpqF/03zLWq1TnyaohzfhHk iDRLZE2F5xD6I36SDHBwu/0je3xiX6gnm5OUtJdeNKcGEhHmoL15cx/dwdrvizC6XHI6x4JNB73m VU7K2zmZAguGipWx8M/g0VnUEkYwPWe0n/DglYPj6IlBsSQiqNQxoMnmnxu LRnuk5JFE33HbIRYhzKS5wpzoxjBZp1tzkZcPsPXibobSwhqWf7MJwQsWeOuprRCh/ 8ZWvM1gOKFyXz11VY02CxJMuH1ItEkwHBFAxawMYGv1QIqQWplgZcCfkcKlgTA0BOFqkY32/1r8jXmhZLfT48Cd2nr9aGrw0lAbVHPM1XsYFea7h oCsj2maonTwOVxULChnHnvbKd8Tx0Y4G3ykr8 tHexK9TvT3bC5SHdM4PBX5KUAzlIHQ1/vKC2y3Rkb22IEnM2EqpldiJMQbyHAwNc51SVosGcDp8hqSZHWfiNpUEdBhkudm uYNZrrbfKjh/ahzN/0p/qsgaaA0dYjEE8p6EWqx7IxveoWDwsw2GQku6ipryelVMKmPLnDfYM7oCEW0/o/m5nqt1mzpOfSOuOLSB1Nf6MlGlwml6/A8lGeMpPUq4OQrgBiPe0NMg9lSM1Pp6y6LxoRTZPuot9O6sY/9hKSvJrWp2yad4 8taUcdFdg hxWBo15a16S 9BcgGfDfP9I9RmjbrOgGFI/7TaykayJ aRPSGPos0V9uztoE6T YTu 3w4cIXfa58ikenB4Azw2r1IxrcVdS9DSR4Kn2It7aTV5rzT46B4ZxXjHloekGwg9lD2xDw fnIVa74qIi3TjdPt8B psaqSE0Ylf7AtRPN6Yeln bx51xK eGG9TbYOTrgFBG8i4cN9HBi9XoZUBK6J4Lsykbom/hI2mOR1h7neGiQmMhxapfm4Uxx88vQa9u8Kf/t5a8r4 MlVzHptC1X760jt7jb7dfOQMuPh8BjhKyL7kc2gsb6Z5ZPyGXPnYj4ftY49WyvtGdvB4bzwF4OqkepOobKtByAxgWaP3w6k9uEVWCsYuxD4Owd6RR8MYoeVq/Olwrzau1IcNDd9L2KaVQr QNXT0gBHmUqgyYahde0z3cx9a1vENTd2LCthy6JiDh6YTu/ aXhbyghsRJpw1IW4jzpdbKaF0SZaVhy3k/rqJsbenU11aYM9UzsJfHUpz0WiQEJ1RC1A3Nz G8 nIRvSw4KokiDhXffp5PShH5IfFmhzeL1et95HtuYmLyX5NRx2rATGNNQ14W3yegzD6GE4jObgEtzb5HA59hvg3bGihHnv7GDLwrYVJf3RiCO59IHB1FY24m324nAamYZhpIVw8jh0bPZgZdPckMzqGX/fyMIPdprJbaMTOE1AwpZ85bSDoS8SzHudn92yAmmbNESdL8ep86QU8WZ g2w  y/TPyN4JMYaTKW8XSlO8teX8/aIxZxw2aH0PbY7J15xGOm93PX1VU17Ajg0WkS420FJQQ0Lx 0kZ05sqnzPeWsbhsPg0gcGYxhQvqe2oraiMWaGlaebk29e2cyC93faM7STSjiQeMdvCd8sYhZS4Ssv9BodUnU6Sp01wbIN7kE8gGJzpTqZ NQa1n1dhPm1Ey8/lOKdVSEj2w0DGuu9eONQs 306/rTq38aG2btZveW2NlXhgENdkGeTk84kFjIxy18bj3wMDAziu/sh4RHBcsx24vEau4C6NbDw/sPLWPz/OIu2d7IRudUKX0YhYRcnR3mc8erA2Acsse0xIIzwA1co98RqkDQR8Au38b0ovE72TxvX7D0/iOQSI4BSFkCj1WnRJRwIJ7R6X6vD0SyIUJJdodqBR/G J6uAwYTOjPB0MVxVYTXPso0vpn6DOM9vsvVDIkGGYgT7Qgk7K6bXjMRRrADSUfbFAnhypFCQDORktnhPnsHkme2RJ0uvnr3JWqzHaTXOQfpcXZOmGsWI9nlpHZ3sfG7vYGiKXohdU5uQlztWQlepD4OQLjjkMz1cFgaB8Ldi7We3SMtEi4LqeL2U11YD07w L4RBeHORpKUL0EioFLaSYDlRUo4kOpPt rE6m3hS9zABXr4UIV449IIv59mxnPAVpfHQXVpA9 91SoE8S4k/ac9W2kFCka06rePx461VeMxXEqAC/EkP6xSrb0Qyd7uMcAfdPH1JIHGGDZN3hXCMXIj4pWMpv5/NA073gdecXkc1Fc38cEjK8hdXep772BkX87uNR4fDFDT4MoOdM83AC/T9kJPsUI9FioKhEpAnY24 Rcm4GanASMNp9HYWN/M MdWkrvqe7L1ASbZZIsbBiJFlToS2e5W1bxfEt3TVlonXkdEOJD9sMsR72W88jreVpWgNK27i/WzdrNzxfdJ5qlIvOIFNi/igu5qOpzSge75aiQ1yp1k9/W5FfXeSomFSrWbhiBZArFKD85FIulH4KUqNd3FmhlFfDH6ACfJH4isHZONyPB/hPdIJxOOQBqTuJLsvgqwWG8nkhtfonbdWYh38mrV/SNFDrKd8BYaNO1Jd5G7ppSJT60x77WdQnT96mxYw1Bd8DoSniZ0/mF7oAFxNuXFmnA ZOvxRyQG83ykecdRSKhWCi29pusRV/8WVU/nINkJ33tzDAfUVTXy3djt/hvb9xM 6qU9YHQCsjkQb6SjA43vyUj/imRCHtLxabLVD7RFNBcj8ZdTTfaWryZ BuLerURiKgPbf16JJJkzZhsb5x5QNaofydtToDP0Pz8O6UKbjAgWAH8zydHGzItU8J6qamREVeRiqQv7GrtbrduIO83JlgX7mP/ Dv 3LsD6hqsXKSk VQnujPNk2NEJCHdJBJO3FqkfM0vtd0ecxzfQxrEbSYGyis1ILO4mrFWms4pmNYM2E7waQcIIF9nIugyqSur54DcrqGvdZ y0CAbgYeBftkkWEax2mq0HbkdiX9sTWVjvF7gUCXdLyqrX7aMeeSE10032hLxAZIPABYoCYY5NtqieeX L536aBGRD77eHxQX4WZK4xHy7EM6V4iBvTRnLJwcdl0yLl1pk8ycqtc1qrOHiJLnnTItztRQJTcQmnMIwwJ3mYupf1lOxL iWntXqpL1t/kRl9FuNnu ZRPds1cTAJtwB0s3JrFc2k78uZJyn1UL3l9ukixiNERj815IcnsGI1nSbcIqUdBfrv9nN7De2mosBBYLVJoZHIKFf/W0eRYTNFs87BSl428ceshgJnIQaDy6Dwo2WMlSyI7js1YjX7QukbMM2JNSmlMibKHYVLIvg3FuAH r4LkCqZefTUhXNRjISzpPmYtln Syw1oMsW4lj1VvZF4kg97W6KkEqZBUgdf236UTZiqRQlCA5e121HNZcHQOrNtpA4AE9QIIeipA9qe2mMd6qr5VircusTbh4wZ3iYF9uFc3WSr6VIYHST0T5dT31OIbWnVr3KRELlISb9e8uJKB6L9YTSjsq8pBwpDuj/HxvPU4I4NzYaxrf7UpC3/ju1PFviuNv802w7ki86On671gtrgbinHmJKDrqJoRwhsOgqrSewpyIEp7HAL kdbXmtuJgPfwbmNQjGdlbkEDt6UgVs5pOSrr/IKUKU2P5qJFN6ixaV5qup6V04hJghkrahhiTrRrJ7RtN6CY1bUE0fQoT5zRxOAyqSxsiLcC6BcnDS5jWq6v2OUj9j2nAPKSsg7sTEm4p8EqCxzcLKSb8GPAVkuR8Uwy/oxbJZPk0jmQD6QS1N2kJ5051sHxyfkvzQOt4kdi1C44GpyNpRFORylidDf9L L7rcVuHkZjZj5B21LHI3j5UJU88iwhVYKqZmpSEMxwGJfnVRFGLtRFpQTyjnSfmZboad7bM8yok5WVpO9/HDUhwdFulkjsBc/ofhKnM1e6EAyk5HiXKkdSMt9p5UvRTR86pnYx0 cjWyiftfB9H6z0cmcRjNa tZk5Hye0qVwfKze28Gh qxO/ZyUhXhNShHEHovn/xxg QEgopSThGOYhXt7IrEM6Hj5HK0D/X1TCvHe7hdOAROifeBi5EHEXTCN83MF7qe7KVfliIVA3f2tYLuTrgpKhGSqR9qBLnB3ocjRQwHYSUeshCMs/jgXuRCsE wlt1B7XnRrvVeyxDwuXGqhp9tI7vMUgNm0HItkof4hdn SgwnvaPFCpTiTuqrZKtIxPOXxUqUt3aPLF6KRl9hBxgmjB9kY3QzDZ8b29Vb33lzZvacbytkjia/cR8PWabzXEd38P0OBKJaT0WKRrcR8e3LYvdkUhN1PfbYU41Ihv2n6v5sCGWF /ohAs2AYv1WMeBdep9G7N9kIDngSbpeDaR9Sm4CvFYNep3NVoYz0NUKsRyM/0gi ftj9H3NSF7UHs5sCOubz4dYhrfI1UiHqvjG0kQwzVtJFyO2vuVFqV7ORKetg7pwVAej8npSsT093RztsVLGWsy7tbDf7IMQCqFPWbRtj1eJeguJG6zmPBR9f2U5Dkx j29sLY/2EgUYUhRSodCPVb6vTdYbd97LF7rVCTLuzSKe3gGKRabdMHVjnhObafLIO0gN2tn7u4IDeFzkYK3f7F4/iFKHp/02G7hM93V6RMrnI213g/5CSJcKGxW29fq9k5foksLegN4niTNZHDEhWhuB6nd3dRWNjL/3R2898Ay8laX0kHwhkVj3aClZXJ9AIkZDHfGULMYYfEZrouhStlW/Adr8ZPdCN6SOhjqgHeTeXLFVKV0uAxS0l2UFdWy MNcsj/JoyS/w8X 7lcV0cpem7kk37fAry185lwkemZMG /zCqzX7pxD8qQi7VU1MRyZDFq6MFn1sJYjWQqdl3CGAS6PA3eai7LdtSz6IJeln 2itKDDBtn3isB5Yq6hMUttl8MsfG60GvQrorzHgUi1Mis1OGuQPbVkQW9VrbF47z7J5bVAvEy1q/M6HeEcTpFmjXVNbF28n23Z 1n3dRFlRbV0cNxrUbo1c2DR293AZ0ideSuT7iNkayFS0g1C9iCtBlPPJLkqWT2MtUiSKtU00IWshvCl71ORTI/bOz7hDEhJc4EBjfXNVBbXseyzfLZnF7Np/r5wNUrigZ7Erqd3M JBvEsfmFXVaIffa2P0GlZyzAYjOXcPY70N8TAk8fG4CH7XKyHGyKUS3YizytmsUvl rCe95pnUwwIkyuMkC5 7Tf/ C3FkxcpP4Us8LaUNOXwuT1porcTrFbWxqaGZtTOLwAtLJuZSnFdD5b66RJPsWCRpcijinYtVk3cv4oKOZDN8Ja1Dn1YiZcGtur77IBEVtyPeu4UBbJAspGbLCKSicCSl3KcDX4Z4/2iVypnEPwu7N5E1Z1lKy15YNZK0epLFz96GxIbui9AGtGrjZyOB7BFnsRi3/zt41Wunx8GSj3MpLaylqaGZok0VtBOcwONIyYVkCRz JYFd3P2VONFUEstHNl LdDXNQroSRdMWrBJJJwrlPT0NKabrIflwlZ/teXmYxaM98CkShraDTobXaSlgmgxHDqEjPH6aBPdoJcD6FCSh0ptkx3e0zrJ3ISFmyXavG5GwwU6D 5NwkK30Gx/djvf3jkXVMxkJV4909wmEHyFlFJJtPsymdSB3hs7dfyLBFKd3BLIdpjZNMg2u1f0zp56b6PubGoEtmoyEez7MPT ThITzAr8y3WM60kLtH8Ctan7MIHl78n2P 5JsUKdjfQ/JR7pXEnh/EyO0cZONcO9a8Jw79LxkI9w8kxo8AngBCXB4D3gVKZb0YbInoA5Nont5H lxHkkUeZMuGr9VVSieXsCXkMTcjlpt t86UcM1cmnW85KtTdnJJufW8apm lKYBqlnM6kzvl1I6kx7YzeyV3Y70Sch/gUYTnzKQ2xUJ82jdMwCtttVEoyM4P4bgAfV/b81SX5HphILJBD DP07F1iPbAEldbnFdJ3s7aEeNOog/YnYFrXJ0ImVE4N7zAX SOQBvmacrhKjPRwjq1Ty923jmB6KbBet0uu2p1rpq7HZS7cMnlSp92Mk1vbaZG7tk6IeniwSF3hbqhJjGdKMMF45RT2RVlDXIYVRrdpdlci 2WR9oG0N1B2ktkZKgsa4GMmgXqYqViwDblORdKXTVKU7OMHz1YFU9Fqo/  LBEAcrubEBGBWUvfS6iIYqBPlZCTc62CT6tGIRDZsBdYi0RZbiW9UiI3Ywm1WlW3CJR8MWvbQmukAXT1t2LBhw4YNGzZs2LBhw4YNGzZs2LBhw4aN2CCLwImcBpKtnBLkM/0SdH8nIGFfiQ6Ry0TKLDhDvH8M9rZPONyBtCe2obgFiUzo7ff68UjUwlV rzuQqO2nEnR/NyEhVrEqN5iGZJGfbWEhWg38OcB7KUj83r9twoXFtyS27XLS4zAk0uJGv9dHIqFIr/q9fooS8bQE3d91SEWsWBHOpfc/3OJ3NyDtpcz4I1Kq4VB7 oTFDCTLImFI9mYehcDXSDm5CabXf6yS7CIOrD9/HVITxFd67gIkEr23SoR/ErwC8alI1H1fJLrjWySJ0Bzp8TMkBtKBxDOW0xL8C9Lb7Ar9vmok3vEbk1S AimP94CqhEVIJeK1qh4 oRLqHr3WTCQHLxAmIf3cxiCR6VXAWXqNm/XabiSV5WJ91gt0kfLFMP5CyfmV6bpXKlnfDvK9NyIFaJuQuM6JSJD5A0gzxzmmc6/X8Zms//cgxXIv0v/PRnLbqvT/ZyLJmr6eDW/S0qOgt6rvJyIpSGNoiVsECeIeiRQaKtb3F5ve7w08hITQ7dG5UJ1oLaAjNGQcr6u4Lyr WCTm8FEdrItNv Unej7678 RcnYTkBJzkwjeRukqJd0GfaAvq7Tw4XmdrDuA Ug5vOf1ofmKlN6q6t5aJJj2M70P1OZ8AWkq2RcpiNNPSXC ibi knVWCvs8jlTCekYJ 6ZO4ClKtg R2ibLdXKO1DHoZrJhLve75pU66QPhZpUIS5Vct9HS93yk6VmYpfA1 u9UXWwe0XtZCfxBx9l37le6MEwxjdFgJHNkmhJ1gi6w00333lvPPU/fr0Qy330Z1gfrta/XhdRH2DP1 dkw4SBd7W4zTbK5 u8PdJKhq3sh0qssTYnjX3p8LZJHZQVXI7laKbqqVvlNzhQly9oQzovRKqF90s9L67qX7yNByb6VdgfBa3oEwo90UflcJbuvvMJ9Kr0O8VvldwH/q/ fiqQgmfE3glfHel2lbiAtKRtJtzHjVbUlUemUx4FVrfuq t9Lf/eTfp//oS4Oo0zP3IenlbiGLnz 7z9jknCjdT6Y646chVR0fs5WKQ9EmT7k65F09eG6SqMr5ku6ml H5JntUFtuAJL28oCeW4fkSw01rapmnKeTIk3PM5RUKTqpt/mpXnWqljzjp3LeosSq4kAPq1sJMNbve/ hE/xwVXWctNTUt4I5es3HVdpUmFS/cUpGH4qRZiWX6USLNCVnnEqQRSq9x6vTKBi8JpV8uC6Qe0zvF hxuUr0N/w 72u0eTFSY/JuHcdmXVjOQBI7z9Hfdo/O6WZ99oN1XC/SMTKnA2Wrup9hEy7wg35LB7aviXDz1HEwDBiCVKvyTW6XDniVTmKvTs4lAa5/kqp67wFfqHp6JtJ4wzdOgVL/G/S6TeqxfFlX3hVK3J8jWwcogRsDXKdOP 8i py0L5Xs2X4SOFC WaXJlDBonY0QKvVnro7JLUqgkWoHztRr n/WbB959LcSxLPaROCMb4ceh jz9FW1blbJVUdLBemjTap4ky7GNSG u9b25AZGuqoHy3SFNdueb6o9sYGW7OEslXRX 10nWIr7A7Suv3 Gqqg9VHJUqsFtxgTT58apA8GMh01qzaU6CX7id86zSNKrW0laoM6VSDBM1bVufjZnjp8a5VDp9Hf9/8eqJZgxXVXNYMQw4zWTU2gurV3si03axGh9Th6/59FPNYF9ukCZ0U/Pec20yOJHYnQxnhzgfR85xyK1Ls0YpFLxeZtewe0h/3JkqDriVXXFf7LvVlvmXKRJxyq1C/xxrnovn1Bpd71Ki2r1mDmUXLlITcrLVP0pNBHuV3qNm1SlvVvfX2YiXKUuDI pnfacfsfNJomQrZPnGqQEQk VzKG2Cq5SR4BZFc3Se5utBL5UJ 1WWpo43qpj91s950WVBMEI97Y6ZS5RNW2RfgYd30b1BA5TovnUbnQcN6gr/jI9ZtDSz 0x1UYe0Ws/rovmiUrI7bq4Xqi/Zao6oXwOqV1qY/7Q5OH1LSzHqGr9oc6Xn u41CJZ2j7fwCQiKyXfqXGKOiD6BZB nxM4YuAOnfCrdLW9jeCNNm5QdXO uvNv1JXRl6qfpsb7RqTeybNqW7ymhPSVY1 p13gdKTzk66j6Y/3sRaq25uj3Xed3H erM2az3kO6Sp3LQozNWbrg P 2Q3WSbtDjbT 70qEL0ya9txeUMKOCfM p6t1bqWP6T5NUdanTw3etp/Ta9/o5Sd7S375Bx6i/3/PK1oViIbJN4zSRZqI6qdbpd5v3Go9VwqzR4yUObB12sr6/Sa89TL2kvj4QD6lNahMuBugRoVc0FNyEbrfkJnAh1uvVYeBTg8IZ67F88GmEbqThpHXl4HBjkBrFez50C3NOqGeQGWb8w72fbtOha BStSMy7aHouvj/AQBGRi2STxexngAAAABJRU5ErkJggg=="/>

For those interested in the details about encoding (such as base64-encoding) the original file size was 11,989 bytes, and the encoded size is now 15,988 bytes which is 1.3x the original size, as is normal with base64-encoding since the encoding standard uses four bytes to represent three of the original bytes, expanding the total size by 1/3 or 33%. This is probably another reason why doing this on the web generally is not advisable.

Moving past the specifics of the data URI we can get into how to build the actual documentation. Within the collector plugin in Eclipse there is a 2011.1/docs/html directory which is where the customized HTML files will go before being joined together to make one large document holding the final documentation. By default this directory has three files: 'Known Issues.html', 'Release Notes.html', and 'Sections.seq'. The first two are basic HTML files, mostly empty, which can be customized with appropriate, plugin-specific content per their titles. Examples for Release Notes could include assumptions made during development, or maybe a bunch of documentation on how to setup the application to send the correct data per the collector's requirements, or future-looking statements about what may come in the next version of the plugin, or how to potentially handle newer version of the application that may otherwise be unsupported. Known Issues, of course, mentions known issues with the plugin such as limits on types of data, or event rates, or other limitations found during testing. For a first release both of these may be blank other than to indicate this is the first release.

The really interesting part is that Sections.seq file, which has a single commented-out line within to give some guidance on its use:

~~~Existing Index Section Name,New Index Section Name(optional),New Index Section Indent(optional),HTML resource

While this is maybe something that makes sense to those familiar with the purpose of the file, in reality this is not enough, or meant to be enough, to get going with expanding the documentation. In fact, these three files have under 1 KiB of information combined, so obviously a lot more is happening that needs to be covered. As a starter, the 2014 Preview documentation has some information on (currently) page 96 in the section titled 'HTML Plug-Iin Documentation'. The documentation briefly discusses 'HTML Document Fragments', which is basically what we are seeing with the Release Notes and Known Issues files which can be edited via any HTML or text editor, depending on the user's preference and ability.

Just to show what happens by default, go ahead and modify the Release Notes and Known Issues files and add some searchable content to them keeping the HTML nature of the documents intact. Run a build from Eclipse by right-clicking on the collector's '2011.1' and choosing 'Create Development Build'. Assuming the build completes properly, somewhere near the end should be a line like the one bolded below:

    [echo] Individual HTML fragements substitution in skeleton doc complete
[echo] HTML Document generated successfully
[copy] Copying 1 file to /home/ab/code/sentinel-plugin-sdk/content/build/Collector/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test/plugin/docs
[move] Moving 1 file to /home/ab/code/sentinel-plugin-sdk/content/build/Collector/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test
[echo] HTML Document generated at : /home/ab/code/sentinel-plugin-sdk/content/build/Collector/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test.html
[echo] ABSoftware_ABProduct_2011.1r1-201412241602-internal-test.html should now be available in the build directory
[xmltask] Setting standalone


[xmltask] Setting standalone
[zip] Building zip: /home/ab/code/sentinel-plugin-sdk/content/build/Collector/ABSoftware_ABProduct_2011.1r1-201412241602-internal-test/
Total time: 3 seconds

Notice a few things here, specifically that the build completed successfully and that the SDK informed you as much at the very end in capital letters; no ambiguity with the build-time success or failure at least. Also, notice that the HTML document is generated and the path to access it is printed out for easy access. Copying this path and dropping it into a regular web browser should show the standard documentation, which should now include your little edits.

The documentation generated by default creates a nice page with a table of contents and information on this particular plugin's connection methods and other properties. Like the ODT-based documentation, a lot of base information is present for any collector but it is intended that the developer add and customize information a bit, which is where the 'seq' files come in. The two sequence (seq) files tell the build process in what order to place the included HTML files, and what "indent' level, so that the document is structured as the author intends. The original Document.seq file looks like this, as taken from sentinel-plugin-sdk/current/sdk/2011.1/Collector/static/docs/html/Document.seq:

~~~Tabs(optional),Index Section Name,HTML resource
,Legal Notice,legal.html
,About This Guide,About This Guide.html
,Contacting Sales Support,Contacting Sales Support.html
,Contacting the Online User Community,Contacting the Online User Community.html
,Additional Documentation,Additional Documentation.html
,Documentation Conventions,Documentation Conventions.html
,Collector Overview,Collector Overview.html
,Supported Products,Supported Products.xsl
,Connection Methods,Connection Methods.xsl
,Observer Configuration,Observer Configuration.html
,Collector Configuration Options,Collector Configuration Options.html
,Predefined Collector Parameters,Predefined Collector Parameters.xsl
,Configuring Time Zone,Configuring Time Zone.html
,Upgrade Procedures,Upgrade Procedures.html
,Collector Customization,Generic Collector Customization.html
,Revision History,Revision History.html
,Known Issues,Known Issues.html
,Release Notes,Release Notes.html

As you can see there are a lot of sections in place already, as each .html file is also present as part of the default SDK. In that same directory are the following files, just to provide a current list with dates and sizes:

-rw-r--r-- 1 ab users  442 Aug 12 13:00 Collector Configuration Options Head.html
-rw-r--r-- 1 ab users 462 Aug 12 13:00 Collector Configuration Options.html
-rw-r--r-- 1 ab users 175 Aug 12 13:00 Collector Overview.html
-rw-r--r-- 1 ab users 4483 Aug 12 13:00 Collector Pack.html
-rw-r--r-- 1 ab users 5772 Aug 12 13:00 Collector Parsing.html
-rw-r--r-- 1 ab users 1639 Aug 12 13:00 Configuration.html
-rw-r--r-- 1 ab users 2704 Aug 12 13:00 Configuring Time Zone.html
-rw-r--r-- 1 ab users 1276 Aug 12 13:00 Connection Methods.html
-rw-r--r-- 1 ab users 5024 Aug 12 13:00 Connection Methods.xsl
-rw-r--r-- 1 ab users 1061 Aug 12 13:00 Document.seq
-rw-r--r-- 1 ab users 1073 Aug 12 13:00 ESM Component Configuration.html
-rw-r--r-- 1 ab users 612 Aug 12 13:00 Exploit Detection Advisor.html
-rw-r--r-- 1 ab users 1966 Aug 12 13:00 Generic Collector Customization.html
-rw-r--r-- 1 ab users 458 Aug 12 13:00 Integration Testing.html
-rw-r--r-- 1 ab users 840 Aug 12 13:00 Observer Configuration.html
-rw-r--r-- 1 ab users 7396 Aug 12 13:00 Predefined Collector Parameters.xsl
-rw-r--r-- 1 ab users 114 Aug 12 13:00 Revision History.html
-rw-r--r-- 1 ab users 219 Aug 12 13:00 Sections.seq
-rw-r--r-- 1 ab users 1255 Aug 12 13:00 Supported Data Sources.html
-rw-r--r-- 1 ab users 1932 Aug 12 13:00 Supported Products.xsl
-rw-r--r-- 1 ab users 3410 Aug 12 13:00 Troubleshooting.html
-rw-r--r-- 1 ab users 5244 Aug 12 13:00 Upgrade Procedures.html

It may also be useful to note that some of these files do not end in .html, but use .xsl instead. As these are XSLT files (XML stylesheets) their intention is not to be used directly but instead to be executed against data in the dev environment created by the collector's developer. It is in this way that dynamic settings from the collector build process, such as application descriptions, connection methods, etc. are all pulled into the documentation at build time. Since an XSLT file needs some kind of input, note that the package.xml, as generated during the build process, is used directly for this input. As a result, to have something dynamically roped into the documentation it needs to exist in the package.xml file.

It is possible, likely even, that some of these default sections are not exactly what you want to have in your custom documentation for a collector. To provide options for this scenario NetIQ has provided the ability to override any of these files, including the Document.seq and Sections.seq files, by placing exactly-named replacement files in the collector's development directory structure. Currently the 2011.1 directory that shows up in Eclipse has several files and a few directories underneath, and the 'docs' directory is, appropriately, where we look for documentation details. Within there is an 'html' directory as mentioned above, and while there are only three files by default more can be added, including copying originals from the main SDK directories for modification on a per-plugin basis. This is particularly neat because it means you can take advantage of what comes by default from NetIQ which is likely applicable to collectors worldwide, but then modify different pieces to meet your own needs, even if that means appending to an existing section without modifying the index (via the Sections.seq file), adding new main sections or subsections (Sections.seq or Document.seq, depending on needs), or removing sections that are not wanted (Document.seq probably). A recent example I had was a request to document, with screenshots, all of the types of events for several custom collectors. Even though they were entirely customized from this SDK, I used a lot of the boilerplate files, customized a few to better meet my needs, and then added a few of my own with a lot of information that did not easily fit in the existing document. Because many of these changes were company, not plugin, specific, I was able to reuse those fragment documents in multiple collectors to further save time. Basically we see all of the benefits programmers have seen for decades in breaking up source files to relevant components, but in documentation.

The Sections.seq file looks like this by default:

~~~Existing Index Section Name,New Index Section Name(optional),New Index Section Indent(optional),HTML resource

Note that the first and last fields are required in this file. The middle fields are only required if you are creating a new subsection, and if you want that new subsection to be indented relative to the original section specified in the first field, respectively.

A few rules surrounding overrides are important to know:

  1. An override (the file overriding the original file) must exist in the plugin's documentation directory (2011.1/docs/html) as mentioned above. The build process needs to find it, and this is where it looks, so put it there. I have not tried using symlinks yet to see if I can put a common file somewhere of my own and then link to it from many plugins' 2011.1/docs/html directory, bu that's on my list of things to try. If symlinking does not work, hard-linking certainly should.

  • The overriding file must have the exact same name as the overridden file. If off at all, keeping in mind we're dealing with computers and computers are case-sensitive by default, the override will not work. Similarly, if the Sections.seq file is used to add to an existing section, or add a subsection, the reference to an existing section must be exactly correct per the original section's name.

  • There are some limitations around what you can do in a Sections.seq file, and other limitations in a Document.seq file. You could probably get away with just having a Document.seq file and defining everything within and modify everything everywhere, but it appears that NetIQ anticipates that most of the we will either override an HTML file completely or else we'll append to it with Sections.seq. Between the two files, there are a lot of great options, and of course it's best to redefine as little as possible to take advantage of SDK improvements in the future as seamlessly as possible.

  • In the Document.seq file the first field is a Tabs field, which indicates how indented the defined section (the one on the current row) is from the root of the document. Only tab characters (0x09) matter and all other whitespace characters are ignored. Also note that a subsection can only ever be indented by one tab more than its parent section, so trying to go from something with zero tabs to something Indented by two tabs is not allowed without an intermediate section indented by one tab. This mostly impacts the created document index and links within the document, as the actual sections of the document are not somehow indented.

For the record, the following are the default locations for HTML files for those plugins which support them:

collectors - sdk/2011.1/Collector/static/docs/html
actions - sdk/2011.1/Action/static/docs/html
reports - sdk/2011.1/Report/static/docs/html
solutions -sdk/2011.1/Solution/static/docs/html

Working on formatting within document sections there are a few common things which may be desirable to know, such as inserting a Note to the reader which stands out as such. For this, the built-in stylesheets (CSS, not XSLT) have a class of 'note' which will properly format things to stand out as a note. Also, because we're dealing with Information Technology (IT), it is likely we'll want to paste code or something formatted like code in our documentation. Surprisingly enough, there is a 'code' class that can be applied to HTML elements just like the 'note' class, so random div/p/span tags can have content formatted appropriately with very little work on our part.

There is more to cover, but this was supposed to be a quick review so perhaps more for later. Some other ideas that have come up after working through this last use of the SDK include using the symlinks (or hardlinks) for vendor-specific things, to try to minimize the need for plugin-specific alterations by instead having one document that is referenced by all of the plugins-specific directories. Another idea may be to do some outside-the-SDK generation of data from source files, particularly when doing images that may update frequently. Getting screenshot for 100 types of events is painful, and then encoding them and placing them in the appropriate files for the build process to consume is not exactly an exercise in anything other than repetition, so creating a quick script to automate that would be worth doing in the future, especially if there is any chance of the events changing as they often do during development.

Happy Computing!
Comment List
Related Discussions