policy/index.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   4 <head>\r
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />\r
   6 <meta name="generator" content="AsciiDoc 8.5.2" />\r
   7 <title>grml policy</title>\r
   8 <style type="text/css">\r
   9 /* Debug borders */\r
  10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
  11 /*\r
  12   border: 1px solid red;\r
  13 */\r
  14 }\r
  15 \r
  16 body {\r
  17   margin: 1em 5% 1em 5%;\r
  18 }\r
  19 \r
  20 a {\r
  21   color: blue;\r
  22   text-decoration: underline;\r
  23 }\r
  24 a:visited {\r
  25   color: fuchsia;\r
  26 }\r
  27 \r
  28 em {\r
  29   font-style: italic;\r
  30   color: navy;\r
  31 }\r
  32 \r
  33 strong {\r
  34   font-weight: bold;\r
  35   color: #083194;\r
  36 }\r
  37 \r
  38 tt {\r
  39   color: navy;\r
  40 }\r
  41 \r
  42 h1, h2, h3, h4, h5, h6 {\r
  43   color: #527bbd;\r
  44   font-family: sans-serif;\r
  45   margin-top: 1.2em;\r
  46   margin-bottom: 0.5em;\r
  47   line-height: 1.3;\r
  48 }\r
  49 \r
  50 h1, h2, h3 {\r
  51   border-bottom: 2px solid silver;\r
  52 }\r
  53 h2 {\r
  54   padding-top: 0.5em;\r
  55 }\r
  56 h3 {\r
  57   float: left;\r
  58 }\r
  59 h3 + * {\r
  60   clear: left;\r
  61 }\r
  62 \r
  63 div.sectionbody {\r
  64   font-family: serif;\r
  65   margin-left: 0;\r
  66 }\r
  67 \r
  68 hr {\r
  69   border: 1px solid silver;\r
  70 }\r
  71 \r
  72 p {\r
  73   margin-top: 0.5em;\r
  74   margin-bottom: 0.5em;\r
  75 }\r
  76 \r
  77 ul, ol, li > p {\r
  78   margin-top: 0;\r
  79 }\r
  80 \r
  81 pre {\r
  82   padding: 0;\r
  83   margin: 0;\r
  84 }\r
  85 \r
  86 span#author {\r
  87   color: #527bbd;\r
  88   font-family: sans-serif;\r
  89   font-weight: bold;\r
  90   font-size: 1.1em;\r
  91 }\r
  92 span#email {\r
  93 }\r
  94 span#revnumber, span#revdate, span#revremark {\r
  95   font-family: sans-serif;\r
  96 }\r
  97 \r
  98 div#footer {\r
  99   font-family: sans-serif;\r
 100   font-size: small;\r
 101   border-top: 2px solid silver;\r
 102   padding-top: 0.5em;\r
 103   margin-top: 4.0em;\r
 104 }\r
 105 div#footer-text {\r
 106   float: left;\r
 107   padding-bottom: 0.5em;\r
 108 }\r
 109 div#footer-badges {\r
 110   float: right;\r
 111   padding-bottom: 0.5em;\r
 112 }\r
 113 \r
 114 div#preamble {\r
 115   margin-top: 1.5em;\r
 116   margin-bottom: 1.5em;\r
 117 }\r
 118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,\r
 119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
 120 div.admonitionblock {\r
 121   margin-top: 1.0em;\r
 122   margin-bottom: 1.5em;\r
 123 }\r
 124 div.admonitionblock {\r
 125   margin-top: 2.0em;\r
 126   margin-bottom: 2.0em;\r
 127   margin-right: 10%;\r
 128   color: #606060;\r
 129 }\r
 130 \r
 131 div.content { /* Block element content. */\r
 132   padding: 0;\r
 133 }\r
 134 \r
 135 /* Block element titles. */\r
 136 div.title, caption.title {\r
 137   color: #527bbd;\r
 138   font-family: sans-serif;\r
 139   font-weight: bold;\r
 140   text-align: left;\r
 141   margin-top: 1.0em;\r
 142   margin-bottom: 0.5em;\r
 143 }\r
 144 div.title + * {\r
 145   margin-top: 0;\r
 146 }\r
 147 \r
 148 td div.title:first-child {\r
 149   margin-top: 0.0em;\r
 150 }\r
 151 div.content div.title:first-child {\r
 152   margin-top: 0.0em;\r
 153 }\r
 154 div.content + div.title {\r
 155   margin-top: 0.0em;\r
 156 }\r
 157 \r
 158 div.sidebarblock > div.content {\r
 159   background: #ffffee;\r
 160   border: 1px solid silver;\r
 161   padding: 0.5em;\r
 162 }\r
 163 \r
 164 div.listingblock > div.content {\r
 165   border: 1px solid silver;\r
 166   background: #f4f4f4;\r
 167   padding: 0.5em;\r
 168 }\r
 169 \r
 170 div.quoteblock, div.verseblock {\r
 171   padding-left: 1.0em;\r
 172   margin-left: 1.0em;\r
 173   margin-right: 10%;\r
 174   border-left: 5px solid #dddddd;\r
 175   color: #777777;\r
 176 }\r
 177 \r
 178 div.quoteblock > div.attribution {\r
 179   padding-top: 0.5em;\r
 180   text-align: right;\r
 181 }\r
 182 \r
 183 div.verseblock > div.content {\r
 184   white-space: pre;\r
 185 }\r
 186 div.verseblock > div.attribution {\r
 187   padding-top: 0.75em;\r
 188   text-align: left;\r
 189 }\r
 190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */\r
 191 div.verseblock + div.attribution {\r
 192   text-align: left;\r
 193 }\r
 194 \r
 195 div.admonitionblock .icon {\r
 196   vertical-align: top;\r
 197   font-size: 1.1em;\r
 198   font-weight: bold;\r
 199   text-decoration: underline;\r
 200   color: #527bbd;\r
 201   padding-right: 0.5em;\r
 202 }\r
 203 div.admonitionblock td.content {\r
 204   padding-left: 0.5em;\r
 205   border-left: 3px solid #dddddd;\r
 206 }\r
 207 \r
 208 div.exampleblock > div.content {\r
 209   border-left: 3px solid #dddddd;\r
 210   padding-left: 0.5em;\r
 211 }\r
 212 \r
 213 div.imageblock div.content { padding-left: 0; }\r
 214 span.image img { border-style: none; }\r
 215 a.image:visited { color: white; }\r
 216 \r
 217 dl {\r
 218   margin-top: 0.8em;\r
 219   margin-bottom: 0.8em;\r
 220 }\r
 221 dt {\r
 222   margin-top: 0.5em;\r
 223   margin-bottom: 0;\r
 224   font-style: normal;\r
 225   color: navy;\r
 226 }\r
 227 dd > *:first-child {\r
 228   margin-top: 0.1em;\r
 229 }\r
 230 \r
 231 ul, ol {\r
 232     list-style-position: outside;\r
 233 }\r
 234 ol.arabic {\r
 235   list-style-type: decimal;\r
 236 }\r
 237 ol.loweralpha {\r
 238   list-style-type: lower-alpha;\r
 239 }\r
 240 ol.upperalpha {\r
 241   list-style-type: upper-alpha;\r
 242 }\r
 243 ol.lowerroman {\r
 244   list-style-type: lower-roman;\r
 245 }\r
 246 ol.upperroman {\r
 247   list-style-type: upper-roman;\r
 248 }\r
 249 \r
 250 div.compact ul, div.compact ol,\r
 251 div.compact p, div.compact p,\r
 252 div.compact div, div.compact div {\r
 253   margin-top: 0.1em;\r
 254   margin-bottom: 0.1em;\r
 255 }\r
 256 \r
 257 div.tableblock > table {\r
 258   border: 3px solid #527bbd;\r
 259 }\r
 260 thead, p.table.header {\r
 261   font-family: sans-serif;\r
 262   font-weight: bold;\r
 263 }\r
 264 tfoot {\r
 265   font-weight: bold;\r
 266 }\r
 267 td > div.verse {\r
 268   white-space: pre;\r
 269 }\r
 270 p.table {\r
 271   margin-top: 0;\r
 272 }\r
 273 /* Because the table frame attribute is overriden by CSS in most browsers. */\r
 274 div.tableblock > table[frame="void"] {\r
 275   border-style: none;\r
 276 }\r
 277 div.tableblock > table[frame="hsides"] {\r
 278   border-left-style: none;\r
 279   border-right-style: none;\r
 280 }\r
 281 div.tableblock > table[frame="vsides"] {\r
 282   border-top-style: none;\r
 283   border-bottom-style: none;\r
 284 }\r
 285 \r
 286 \r
 287 div.hdlist {\r
 288   margin-top: 0.8em;\r
 289   margin-bottom: 0.8em;\r
 290 }\r
 291 div.hdlist tr {\r
 292   padding-bottom: 15px;\r
 293 }\r
 294 dt.hdlist1.strong, td.hdlist1.strong {\r
 295   font-weight: bold;\r
 296 }\r
 297 td.hdlist1 {\r
 298   vertical-align: top;\r
 299   font-style: normal;\r
 300   padding-right: 0.8em;\r
 301   color: navy;\r
 302 }\r
 303 td.hdlist2 {\r
 304   vertical-align: top;\r
 305 }\r
 306 div.hdlist.compact tr {\r
 307   margin: 0;\r
 308   padding-bottom: 0;\r
 309 }\r
 310 \r
 311 .comment {\r
 312   background: yellow;\r
 313 }\r
 314 \r
 315 .footnote, .footnoteref {\r
 316   font-size: 0.8em;\r
 317 }\r
 318 \r
 319 span.footnote, span.footnoteref {\r
 320   vertical-align: super;\r
 321 }\r
 322 \r
 323 #footnotes {\r
 324   margin: 20px 0 20px 0;\r
 325   padding: 7px 0 0 0;\r
 326 }\r
 327 \r
 328 #footnotes div.footnote {\r
 329   margin: 0 0 5px 0;\r
 330 }\r
 331 \r
 332 #footnotes hr {\r
 333   border: none;\r
 334   border-top: 1px solid silver;\r
 335   height: 1px;\r
 336   text-align: left;\r
 337   margin-left: 0;\r
 338   width: 20%;\r
 339   min-width: 100px;\r
 340 }\r
 341 \r
 342 \r
 343 @media print {\r
 344   div#footer-badges { display: none; }\r
 345 }\r
 346 \r
 347 div#toc {\r
 348   margin-bottom: 2.5em;\r
 349 }\r
 350 \r
 351 div#toctitle {\r
 352   color: #527bbd;\r
 353   font-family: sans-serif;\r
 354   font-size: 1.1em;\r
 355   font-weight: bold;\r
 356   margin-top: 1.0em;\r
 357   margin-bottom: 0.1em;\r
 358 }\r
 359 \r
 360 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {\r
 361   margin-top: 0;\r
 362   margin-bottom: 0;\r
 363 }\r
 364 div.toclevel2 {\r
 365   margin-left: 2em;\r
 366   font-size: 0.9em;\r
 367 }\r
 368 div.toclevel3 {\r
 369   margin-left: 4em;\r
 370   font-size: 0.9em;\r
 371 }\r
 372 div.toclevel4 {\r
 373   margin-left: 6em;\r
 374   font-size: 0.9em;\r
 375 }\r
 376 /* Workarounds for IE6's broken and incomplete CSS2. */\r
 377 \r
 378 div.sidebar-content {\r
 379   background: #ffffee;\r
 380   border: 1px solid silver;\r
 381   padding: 0.5em;\r
 382 }\r
 383 div.sidebar-title, div.image-title {\r
 384   color: #527bbd;\r
 385   font-family: sans-serif;\r
 386   font-weight: bold;\r
 387   margin-top: 0.0em;\r
 388   margin-bottom: 0.5em;\r
 389 }\r
 390 \r
 391 div.listingblock div.content {\r
 392   border: 1px solid silver;\r
 393   background: #f4f4f4;\r
 394   padding: 0.5em;\r
 395 }\r
 396 \r
 397 div.quoteblock-attribution {\r
 398   padding-top: 0.5em;\r
 399   text-align: right;\r
 400 }\r
 401 \r
 402 div.verseblock-content {\r
 403   white-space: pre;\r
 404 }\r
 405 div.verseblock-attribution {\r
 406   padding-top: 0.75em;\r
 407   text-align: left;\r
 408 }\r
 409 \r
 410 div.exampleblock-content {\r
 411   border-left: 3px solid #dddddd;\r
 412   padding-left: 0.5em;\r
 413 }\r
 414 \r
 415 /* IE6 sets dynamically generated links as visited. */\r
 416 div#toc a:visited { color: blue; }\r
 417 </style>\r
 418 <script type="text/javascript">\r
 419 /*<![CDATA[*/\r
 420 window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}\r
 421 var asciidoc = {  // Namespace.\r
 422 \r
 423 /////////////////////////////////////////////////////////////////////\r
 424 // Table Of Contents generator\r
 425 /////////////////////////////////////////////////////////////////////\r
 426 \r
 427 /* Author: Mihai Bazon, September 2002\r
 428  * http://students.infoiasi.ro/~mishoo\r
 429  *\r
 430  * Table Of Content generator\r
 431  * Version: 0.4\r
 432  *\r
 433  * Feel free to use this script under the terms of the GNU General Public\r
 434  * License, as long as you do not remove or alter this notice.\r
 435  */\r
 436 \r
 437  /* modified by Troy D. Hanson, September 2006. License: GPL */\r
 438  /* modified by Stuart Rackham, 2006, 2009. License: GPL */\r
 439 \r
 440 // toclevels = 1..4.\r
 441 toc: function (toclevels) {\r
 442 \r
 443   function getText(el) {\r
 444     var text = "";\r
 445     for (var i = el.firstChild; i != null; i = i.nextSibling) {\r
 446       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.\r
 447         text += i.data;\r
 448       else if (i.firstChild != null)\r
 449         text += getText(i);\r
 450     }\r
 451     return text;\r
 452   }\r
 453 \r
 454   function TocEntry(el, text, toclevel) {\r
 455     this.element = el;\r
 456     this.text = text;\r
 457     this.toclevel = toclevel;\r
 458   }\r
 459 \r
 460   function tocEntries(el, toclevels) {\r
 461     var result = new Array;\r
 462     var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');\r
 463     // Function that scans the DOM tree for header elements (the DOM2\r
 464     // nodeIterator API would be a better technique but not supported by all\r
 465     // browsers).\r
 466     var iterate = function (el) {\r
 467       for (var i = el.firstChild; i != null; i = i.nextSibling) {\r
 468         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {\r
 469           var mo = re.exec(i.tagName);\r
 470           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {\r
 471             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);\r
 472           }\r
 473           iterate(i);\r
 474         }\r
 475       }\r
 476     }\r
 477     iterate(el);\r
 478     return result;\r
 479   }\r
 480 \r
 481   var toc = document.getElementById("toc");\r
 482   var entries = tocEntries(document.getElementById("content"), toclevels);\r
 483   for (var i = 0; i < entries.length; ++i) {\r
 484     var entry = entries[i];\r
 485     if (entry.element.id == "")\r
 486       entry.element.id = "_toc_" + i;\r
 487     var a = document.createElement("a");\r
 488     a.href = "#" + entry.element.id;\r
 489     a.appendChild(document.createTextNode(entry.text));\r
 490     var div = document.createElement("div");\r
 491     div.appendChild(a);\r
 492     div.className = "toclevel" + entry.toclevel;\r
 493     toc.appendChild(div);\r
 494   }\r
 495   if (entries.length == 0)\r
 496     toc.parentNode.removeChild(toc);\r
 497 },\r
 498 \r
 499 \r
 500 /////////////////////////////////////////////////////////////////////\r
 501 // Footnotes generator\r
 502 /////////////////////////////////////////////////////////////////////\r
 503 \r
 504 /* Based on footnote generation code from:\r
 505  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html\r
 506  */\r
 507 \r
 508 footnotes: function () {\r
 509   var cont = document.getElementById("content");\r
 510   var noteholder = document.getElementById("footnotes");\r
 511   var spans = cont.getElementsByTagName("span");\r
 512   var refs = {};\r
 513   var n = 0;\r
 514   for (i=0; i<spans.length; i++) {\r
 515     if (spans[i].className == "footnote") {\r
 516       n++;\r
 517       // Use [\s\S] in place of . so multi-line matches work.\r
 518       // Because JavaScript has no s (dotall) regex flag.\r
 519       note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];\r
 520       noteholder.innerHTML +=\r
 521         "<div class='footnote' id='_footnote_" + n + "'>" +\r
 522         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +\r
 523         n + "</a>. " + note + "</div>";\r
 524       spans[i].innerHTML =\r
 525         "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +\r
 526         "' title='View footnote' class='footnote'>" + n + "</a>]";\r
 527       var id =spans[i].getAttribute("id");\r
 528       if (id != null) refs["#"+id] = n;\r
 529     }\r
 530   }\r
 531   if (n == 0)\r
 532     noteholder.parentNode.removeChild(noteholder);\r
 533   else {\r
 534     // Process footnoterefs.\r
 535     for (i=0; i<spans.length; i++) {\r
 536       if (spans[i].className == "footnoteref") {\r
 537         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");\r
 538         href = href.match(/#.*/)[0];  // Because IE return full URL.\r
 539         n = refs[href];\r
 540         spans[i].innerHTML =\r
 541           "[<a href='#_footnote_" + n +\r
 542           "' title='View footnote' class='footnote'>" + n + "</a>]";\r
 543       }\r
 544     }\r
 545   }\r
 546 }\r
 547 \r
 548 }\r
 549 /*]]>*/\r
 550 </script>\r
 551 </head>\r
 552 <body>\r
 553 <div id="header">\r
 554 <h1>grml policy</h1>\r
 555 <div id="toc">\r
 556   <div id="toctitle">Table of Contents</div>\r
 557   <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>\r
 558 </div>\r
 559 </div>\r
 560 <div id="content">\r
 561 <div id="preamble">\r
 562 <div class="sectionbody">\r
 563 <div class="sidebarblock">\r
 564 <div class="sidebar-content">\r
 565 <div class="paragraph"><p>Important! This file is not yet official - work in progress.</p></div>\r
 566 </div></div>\r
 567 </div>\r
 568 </div>\r
 569 <h2 id="_preface">1. Preface</h2>\r
 570 <div class="sectionbody">\r
 571 <div class="paragraph"><p>This is a short documentation describing different policies used at and for\r
 572 <a href="http://grml.org/">grml</a>.</p></div>\r
 573 </div>\r
 574 <h2 id="_packaging_software">2. Packaging Software</h2>\r
 575 <div class="sectionbody">\r
 576 <div class="paragraph"><p>If you are not yet familiar with <strong>creating</strong> Debian packaging, useful\r
 577 resources are the <a href="http://www.debian.org/doc/maint-guide/">Debian New\r
 578 Maintainers' Guide</a> and\r
 579 <a href="http://www.debian.org/doc/manuals/developers-reference/index.en.html">The\r
 580 Debian Developer&#8217;s Reference</a>.</p></div>\r
 581 <div class="paragraph"><p>Software that should be <strong>added</strong> to the grml repository (and as a\r
 582 consequence being available for inclusion in grml) must be packaged\r
 583 according to the\r
 584 <a href="http://www.debian.org/doc/debian-policy/index.html">Debian policy</a>.\r
 585 The Debian packages should be\r
 586 <a href="http://lintian.debian.org/">lintian</a>-clean and have to provide manpages\r
 587 for the shipped executables. The package should either be maintained inside\r
 588 a git repository hosted at <a href="http://git.grml.org/">git.grml.org</a> or be\r
 589 part of the official debian repository.\r
 590 If a package is a grml specific package (so upstream is different from\r
 591 the grml-team) the Debian package has to start with the suffix <em>grml-</em> (so\r
 592 the grml specific packages can be identified easily).</p></div>\r
 593 <div class="paragraph"><p>If you want to see software included in grml but won&#8217;t be able to deal with\r
 594 the Debian package please <a href="http://grml.org/report/">send your feature\r
 595 request to the grml-team</a> or by sending a mail to\r
 596 <a href="mailto:bts@bts.grml.org">bts@bts.grml.org</a>, which will add an issue to\r
 597 <a href="http://bts.grml.org">bts.grml.org</a>.</p></div>\r
 598 <div class="paragraph"><p>Uploading Debian packages to <a href="http://deb.grml.org/">the grml pool</a> is\r
 599 restricted to the ftp-masters (being Michael Prokop and Alexander Wirt at\r
 600 the time of writing this document).</p></div>\r
 601 <div class="paragraph"><p>As a long term goal the Debian packages used at grml should be provided to\r
 602 the official Debian distribution using the official\r
 603 <a href="http://www.debian.org/devel/wnpp/">WNPP / ITP (Intend To Package)</a>\r
 604 procedure.</p></div>\r
 605 </div>\r
 606 <h2 id="_adding_software_to_grml">3. Adding Software to grml</h2>\r
 607 <div class="sectionbody">\r
 608 <div class="paragraph"><p>If you plan to write software for inclusion and distribution by grml you\r
 609 should be aware of the following requirements:</p></div>\r
 610 <div class="ulist"><ul>\r
 611 <li>\r
 612 <p>\r
 613 The software has to be licensed under an\r
 614 <a href="http://www.opensource.org/licenses">OSI approved license</a> and should\r
 615 follow the <a href="http://www.debian.org/social_contract#guidelines">The Debian\r
 616 Free Software Guidelines (DFSG)</a>. The grml-team prefers the\r
 617 <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License\r
 618 (GPL)</a>. If you want to see your patch/script/software included in a core\r
 619 grml package it has to be licensed under the GPL as well.\r
 620 </p>\r
 621 </li>\r
 622 <li>\r
 623 <p>\r
 624 Your software has to provide documentation. The package must provide at\r
 625 least an up2date manpage. The grml-team prefers documentation written in\r
 626 <a href="http://www.methods.co.nz/asciidoc/">asciidoc</a>, see\r
 627 <a href="http://grml.org/docs/">grml.org/docs/</a> and\r
 628 <a href="http://hg.grml.org/grml-debootstrap/file/tip/grml-debootstrap.8.txt">grml-debootstrap.8.txt</a>\r
 629 for a real-life example.\r
 630 </p>\r
 631 </li>\r
 632 <li>\r
 633 <p>\r
 634 Your software should be as platform independent as possible and should\r
 635 work at least on x86, x86_64 (amd64) and ppc.\r
 636 </p>\r
 637 </li>\r
 638 </ul></div>\r
 639 </div>\r
 640 <h2 id="_contributing_patches_to_grml">4. Contributing patches to grml</h2>\r
 641 <div class="sectionbody">\r
 642 <div class="paragraph"><p>Software written by and maintained by the grml-team is available at\r
 643 <a href="http://git.grml.org/">git.grml.org</a>. If you plan to provide a patch to\r
 644 the grml-team you can checkout the according repository and create a patch\r
 645 using the <em>git diff</em> or even better the <em>git format-patch</em> command. Usage\r
 646 example:</p></div>\r
 647 <div class="listingblock">\r
 648 <div class="content"><!-- Generator: GNU source-highlight 3.1.3\r
 649 by Lorenzo Bettini\r
 650 http://www.lorenzobettini.it\r
 651 http://www.gnu.org/software/src-highlite -->\r
 652 <pre><tt><span style="color: #990000">%</span> git clone git<span style="color: #990000">:</span>//git<span style="color: #990000">.</span>grml<span style="color: #990000">.</span>org/grml-policy<span style="color: #990000">.</span>git\r
 653 <span style="color: #990000">%</span> cd grml-policy\r
 654 <span style="color: #990000">%</span> git checkout -b mygreatfeature\r
 655 <span style="color: #990000">%</span> <span style="color: #990000">[</span>hack hack hack<span style="color: #990000">]</span>\r
 656 <span style="color: #990000">%</span> git commit -a\r
 657 <span style="color: #990000">%</span> git format-patch master</tt></pre></div></div>\r
 658 <div class="paragraph"><p>And mail the resulting patches to the grml-team with your favourite mail\r
 659 client or using <em>git send-email</em>. The maintainer of the according\r
 660 repository is listed in the owner-column on\r
 661 <a href="http://git.grml.org/">git.grml.org</a>. You are free to\r
 662 <a href="http://grml.org/contact/">contact the grml-team directly via mail</a>,\r
 663 <a href="http://bts.grml.org/">the grml bug tracking system</a>, or the\r
 664 <a href="http://grml.org/mailinglist/">grml-mailinglist</a> as well.</p></div>\r
 665 <div class="paragraph"><p>More details regarding use of git within grml is available at\r
 666 <a href="http://grml.org/git/">grml.org/git/</a>.</p></div>\r
 667 </div>\r
 668 <h2 id="_common_practices_for_writing_code">5. Common practices for writing code</h2>\r
 669 <div class="sectionbody">\r
 670 <h3 id="_header_information">5.1. Header information</h3><div style="clear:left"></div>\r
 671 <div class="paragraph"><p>Every script should provide a header which should look like this:</p></div>\r
 672 <div class="literalblock">\r
 673 <div class="content">\r
 674 <pre><tt>#!/bin/sh\r
 675 # Filename:      grml2hd\r
 676 # Purpose:       install grml to harddisk\r
 677 # Authors:       grml-team (grml.org), (c) Andreas Gredler &lt;jimmy@grml.org&gt;, Michael Prokop &lt;mika@grml.org&gt;\r
 678 # Bug-Reports:   see http://grml.org/bugs/\r
 679 # License:       This file is licensed under the GPL v2.\r
 680 # Latest change: Thu Sep 13 23:00:56 CEST 2007 [mika]\r
 681 ################################################################################</tt></pre>\r
 682 </div></div>\r
 683 <h3 id="_footer_information">5.2. Footer information</h3><div style="clear:left"></div>\r
 684 <div class="paragraph"><p>Most developers of the grml-team use Vim as their favourite editor.\r
 685 Therefor providing a modeline at the end of the sourcefile is commonly used\r
 686 to indicate the favourite editing mode/style. Usage example:</p></div>\r
 687 <div class="literalblock">\r
 688 <div class="content">\r
 689 <pre><tt># vim: autoindent filetype=sh expandtab shiftwidth=4</tt></pre>\r
 690 </div></div>\r
 691 <h3 id="_grml_shellscript_library">5.3. grml shellscript library</h3><div style="clear:left"></div>\r
 692 <div class="paragraph"><p>The grml system provides several shellscript resources. The package\r
 693 grml-etc-core provides the files /etc/grml/lsb-functions and\r
 694 /etc/grml/script-functions, the package grml-shlib ships /etc/grml/sh-lib.</p></div>\r
 695 <h4 id="_etc_grml_lsb_functions">5.3.1. /etc/grml/lsb-functions</h4>\r
 696 <div class="paragraph"><p>The file /etc/grml/lsb-functions is used within init-scripts and init-style\r
 697 scripts (like shellscripts handling with services) and is supposed to be\r
 698 POSIX-compatible. Usage example:</p></div>\r
 699 <div class="listingblock">\r
 700 <div class="content"><!-- Generator: GNU source-highlight 3.1.3\r
 701 by Lorenzo Bettini\r
 702 http://www.lorenzobettini.it\r
 703 http://www.gnu.org/software/src-highlite -->\r
 704 <pre><tt><span style="color: #990000">%</span> <span style="font-weight: bold"><span style="color: #0000FF">source</span></span> /etc/grml/lsb-functions\r
 705 <span style="color: #990000">%</span> einfo <span style="color: #FF0000">"Starting foobar."</span> <span style="color: #990000">;</span> /bin/true <span style="color: #990000">;</span> eend <span style="color: #009900">$?</span>\r
 706  <span style="color: #990000">*</span> Starting foobar<span style="color: #990000">.</span>                                  <span style="color: #990000">[</span> ok <span style="color: #990000">]</span>\r
 707 <span style="color: #990000">%</span> einfo <span style="color: #FF0000">"Starting foobar."</span> <span style="color: #990000">;</span> /bin/false <span style="color: #990000">;</span> eend <span style="color: #009900">$?</span>\r
 708  <span style="color: #990000">*</span> Starting foobar<span style="color: #990000">.</span>                                  <span style="color: #990000">[</span> <span style="color: #990000">!!</span> <span style="color: #990000">]</span>\r
 709 <span style="color: #990000">%</span></tt></pre></div></div>\r
 710 <div class="paragraph"><p>If you want to provide output on the plain console (without using an\r
 711 interface like <a href="http://invisible-island.net/dialog/">dialog</a> or\r
 712 <a href="http://www.clifford.at/stfl/">stfl</a>) you should consider the use of\r
 713 /etc/grml/lsb-functions so look and feel of grml-scripts is as consistent\r
 714 as possible.</p></div>\r
 715 <h4 id="_etc_grml_script_functions">5.3.2. /etc/grml/script-functions</h4>\r
 716 <div class="paragraph"><p>The file /etc/grml/script-functions provides common functions used inside\r
 717 several scripts, like check4root (check for root-permissions), iszsh (check\r
 718 for running zsh). The file is supposed to work with every POSIX-compatible\r
 719 shell (otherwise it&#8217;s a bug).</p></div>\r
 720 <h4 id="_etc_grml_sh_lib">5.3.3. /etc/grml/sh-lib</h4>\r
 721 <div class="paragraph"><p>The file /etc/grml/sh-lib provides a smiliar functionality like\r
 722 /etc/grml/lsb-functions and /etc/grml/script-functions do. As a long term\r
 723 goal the functionality of this file should be merged with the one of\r
 724 lsb-functions and script-functions.</p></div>\r
 725 <h3 id="_good_practices_for_shellscript">5.4. Good practices for shellscript</h3><div style="clear:left"></div>\r
 726 <div class="ulist"><ul>\r
 727 <li>\r
 728 <p>\r
 729 <strong>shebang line:</strong> if you use <em>#!/bin/sh</em> as the shebang line of your\r
 730 shellscript you should make sure that the script runs under every\r
 731 POSIX-compatible shell. A good test is the use of /bin/dash for /bin/sh. If\r
 732 you use bash/zsh/ksh93/&#8230;  specific features please use the according\r
 733 shell in the shebang line of your script.\r
 734 </p>\r
 735 </li>\r
 736 <li>\r
 737 <p>\r
 738 <strong>check for appropriate permissions:</strong> if you need root permissions you\r
 739 should make sure that your script is running as user root (take a look at\r
 740 check4root function provided by /etc/grml/script-functions).\r
 741 </p>\r
 742 </li>\r
 743 <li>\r
 744 <p>\r
 745 <strong>clean up when being interrupted and on exit:</strong> your script should not leave\r
 746 any temporary files (unless intented for debugging purposes of course).\r
 747 Usage example:\r
 748 </p>\r
 749 <div class="listingblock">\r
 750 <div class="content"><!-- Generator: GNU source-highlight 3.1.3\r
 751 by Lorenzo Bettini\r
 752 http://www.lorenzobettini.it\r
 753 http://www.gnu.org/software/src-highlite -->\r
 754 <pre><tt><span style="color: #009900">TMPFILE</span><span style="color: #990000">=</span><span style="color: #009900">$(</span>mktemp <span style="color: #009900">${TMP}</span>/grml2hd<span style="color: #990000">.</span>XXXXXX<span style="color: #990000">)</span>\r
 755 <span style="font-weight: bold"><span style="color: #000000">bailout()</span></span> {\r
 756   rm -f <span style="color: #FF0000">"$TMPFILE"</span>\r
 757   <span style="color: #990000">[</span> -n <span style="color: #FF0000">"$1"</span> <span style="color: #990000">]</span> <span style="color: #990000">&amp;&amp;</span> <span style="color: #009900">EXIT</span><span style="color: #990000">=</span><span style="color: #FF0000">"$1"</span> <span style="color: #990000">||</span> <span style="color: #009900">EXIT</span><span style="color: #990000">=</span><span style="color: #FF0000">"1"</span>\r
 758   <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span> <span style="color: #FF0000">"$EXIT"</span>\r
 759 }\r
 760 <span style="font-weight: bold"><span style="color: #0000FF">trap</span></span> bailout <span style="color: #993399">1</span> <span style="color: #993399">2</span> <span style="color: #993399">3</span> <span style="color: #993399">15</span>\r
 761 <span style="color: #009900">$CODE</span>\r
 762 bailout <span style="color: #993399">0</span></tt></pre></div></div>\r
 763 </li>\r
 764 <li>\r
 765 <p>\r
 766 <strong>use of subshells:</strong> please use <em>$(&#8230;)</em> instead of <em>`&#8230;\`</em>.\r
 767 </p>\r
 768 <div class="paragraph"><p>It allows nesting of commands in a more clearly and easier way.\r
 769 Therefore any shell code might appear within the parentheses, since\r
 770 the only time parentheses occur unquoted is in pairs.<br />\r
 771 With backquotes however any unquoted <em>`_ within the form _\`&#8230;\`</em>\r
 772 would end the quotes immediately.</p></div>\r
 773 <div class="paragraph"><p>Consider the following as an example on readability:</p></div>\r
 774 <div class="listingblock">\r
 775 <div class="content"><!-- Generator: GNU source-highlight 3.1.3\r
 776 by Lorenzo Bettini\r
 777 http://www.lorenzobettini.it\r
 778 http://www.gnu.org/software/src-highlite -->\r
 779 <pre><tt><span style="color: #990000">%</span> echo <span style="color: #FF0000">"Tomorrow's date: `expr </span><span style="color: #CC33CC">\`</span><span style="color: #FF0000">date +%d</span><span style="color: #CC33CC">\`</span><span style="color: #FF0000"> + 1`.`date +%m`."</span>\r
 780 <span style="color: #990000">%</span> echo <span style="color: #FF0000">"Tomorrow's date: $(expr $(date +%d) + 1).$(date +%m)."</span></tt></pre></div></div>\r
 781 <div class="paragraph"><p>Furthermore it can get quite tricky to get the right level of quotes\r
 782 when using backquotes.</p></div>\r
 783 <div class="listingblock">\r
 784 <div class="content"><!-- Generator: GNU source-highlight 3.1.3\r
 785 by Lorenzo Bettini\r
 786 http://www.lorenzobettini.it\r
 787 http://www.gnu.org/software/src-highlite -->\r
 788 <pre><tt><span style="color: #990000">%</span> print <span style="color: #FF0000">"`echo </span><span style="color: #CC33CC">\"</span><span style="color: #FF0000">hello</span><span style="color: #CC33CC">\"</span><span style="color: #FF0000">`"</span>\r
 789 hello\r
 790 <span style="color: #990000">%</span> print <span style="color: #FF0000">"$(echo </span><span style="color: #CC33CC">\"</span><span style="color: #FF0000">hello</span><span style="color: #CC33CC">\"</span><span style="color: #FF0000">)"</span>\r
 791 <span style="color: #FF0000">"hello"</span></tt></pre></div></div>\r
 792 <div class="paragraph"><p>For further reading have a look at\r
 793 <a href="http://zsh.dotsrc.org/Guide/zshguide05.html#l11">A User&#8217;s Guide to the\r
 794 Z Shell</a>\r
 795 and <a href="http://zsh.sourceforge.net/Intro/intro_7.html#SEC7">Introduction to\r
 796 the Z Shell</a></p></div>\r
 797 </li>\r
 798 <li>\r
 799 <p>\r
 800 <strong>if &#8230; then &#8230; else &#8230; etc.</strong>: Use the coding style used in other\r
 801 shell scripts shipped by grml, like:\r
 802 </p>\r
 803 <div class="listingblock">\r
 804 <div class="content"><!-- Generator: GNU source-highlight 3.1.3\r
 805 by Lorenzo Bettini\r
 806 http://www.lorenzobettini.it\r
 807 http://www.gnu.org/software/src-highlite -->\r
 808 <pre><tt><span style="font-style: italic"><span style="color: #9A1900">## use the following forms:</span></span>\r
 809 \r
 810 <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -n <span style="color: #FF0000">"$FOO"</span> <span style="color: #990000">]</span> <span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span>\r
 811     bar\r
 812 <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>\r
 813     baz\r
 814 <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>\r
 815 \r
 816 <span style="font-weight: bold"><span style="color: #0000FF">while</span></span> <span style="color: #990000">[</span> -n <span style="color: #FF0000">"$FOO"</span> <span style="color: #990000">]</span> <span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>\r
 817     bar\r
 818 <span style="font-weight: bold"><span style="color: #0000FF">done</span></span>\r
 819 \r
 820 <span style="font-style: italic"><span style="color: #9A1900">## instead of these:</span></span>\r
 821 \r
 822 <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -n <span style="color: #FF0000">"$FOO"</span> <span style="color: #990000">]</span>\r
 823 <span style="font-weight: bold"><span style="color: #0000FF">then</span></span>\r
 824     bar\r
 825 <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>\r
 826     baz\r
 827 <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>\r
 828 \r
 829 <span style="font-weight: bold"><span style="color: #0000FF">while</span></span> <span style="color: #990000">[</span> -n <span style="color: #FF0000">"$FOO"</span> <span style="color: #990000">]</span>\r
 830 <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>\r
 831     bar\r
 832 <span style="font-weight: bold"><span style="color: #0000FF">done</span></span></tt></pre></div></div>\r
 833 </li>\r
 834 <li>\r
 835 <p>\r
 836 <strong>whitespace:</strong> make sure you indent your code and use blank lines where\r
 837 according. Commonly accepted textwidth is 80 chars. (TODO: provide some\r
 838 more information&#8230;)\r
 839 </p>\r
 840 </li>\r
 841 <li>\r
 842 <p>\r
 843 <strong>indenting and use of tabs:</strong> the grml-team prefers to <strong>not</strong> use any\r
 844 tabs inside their code. Please use 4 spaces instead of a tab instead\r
 845 (<em>tabstop=4</em> and <em>set expandtab</em> when using Vim editor). To replace tabs\r
 846 with spaces you can use <em>:set expandtab</em> and <em>:retab</em> using Vim editor.\r
 847 </p>\r
 848 </li>\r
 849 <li>\r
 850 <p>\r
 851 <strong>no trailing whitespaces:</strong> make sure your code does not contain any\r
 852 trailing whitespaces. Remove them inside Vim editor running <em>:%s/\s\+$//</em>\r
 853 and make them visible using for example <em>:set\r
 854 listchars=eol:$,precedes:«,extends:»,tab:»·,trail:·</em>.\r
 855 </p>\r
 856 </li>\r
 857 </ul></div>\r
 858 </div>\r
 859 <h2 id="_about_this_document">6. About this document</h2>\r
 860 <div class="sectionbody">\r
 861 <div class="paragraph"><p>&#169; Michael Prokop &lt;<a href="mailto:mika@grml.org">mika@grml.org</a>&gt;; HTML version powered by <a href="http://www.methods.co.nz/asciidoc/">asciidoc</a>.</p></div>\r
 862 </div>\r
 863 </div>\r
 864 <div id="footnotes"><hr /></div>\r
 865 <div id="footer">\r
 866 <div id="footer-text">\r
 867 Last updated 2010-02-28 01:48:56 CEST\r
 868 </div>\r
 869 </div>\r
 870 </body>\r
 871 </html>\r