online-docs/grml-policy.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.2.2" />\r
   7 <style type="text/css">\r
   8 /* Debug borders */\r
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
  10 /*\r
  11   border: 1px solid red;\r
  12 */\r
  13 }\r
  14 \r
  15 body {\r
  16   margin: 1em 5% 1em 5%;\r
  17 }\r
  18 \r
  19 a {\r
  20   color: blue;\r
  21   text-decoration: underline;\r
  22 }\r
  23 a:visited {\r
  24   color: fuchsia;\r
  25 }\r
  26 \r
  27 em {\r
  28   font-style: italic;\r
  29 }\r
  30 \r
  31 strong {\r
  32   font-weight: bold;\r
  33 }\r
  34 \r
  35 tt {\r
  36   color: navy;\r
  37 }\r
  38 \r
  39 h1, h2, h3, h4, h5, h6 {\r
  40   color: #527bbd;\r
  41   font-family: sans-serif;\r
  42   margin-top: 1.2em;\r
  43   margin-bottom: 0.5em;\r
  44   line-height: 1.3;\r
  45 }\r
  46 \r
  47 h1 {\r
  48   border-bottom: 2px solid silver;\r
  49 }\r
  50 h2 {\r
  51   border-bottom: 2px solid silver;\r
  52   padding-top: 0.5em;\r
  53 }\r
  54 \r
  55 div.sectionbody {\r
  56   font-family: serif;\r
  57   margin-left: 0;\r
  58 }\r
  59 \r
  60 hr {\r
  61   border: 1px solid silver;\r
  62 }\r
  63 \r
  64 p {\r
  65   margin-top: 0.5em;\r
  66   margin-bottom: 0.5em;\r
  67 }\r
  68 \r
  69 pre {\r
  70   padding: 0;\r
  71   margin: 0;\r
  72 }\r
  73 \r
  74 span#author {\r
  75   color: #527bbd;\r
  76   font-family: sans-serif;\r
  77   font-weight: bold;\r
  78   font-size: 1.1em;\r
  79 }\r
  80 span#email {\r
  81 }\r
  82 span#revision {\r
  83   font-family: sans-serif;\r
  84 }\r
  85 \r
  86 div#footer {\r
  87   font-family: sans-serif;\r
  88   font-size: small;\r
  89   border-top: 2px solid silver;\r
  90   padding-top: 0.5em;\r
  91   margin-top: 4.0em;\r
  92 }\r
  93 div#footer-text {\r
  94   float: left;\r
  95   padding-bottom: 0.5em;\r
  96 }\r
  97 div#footer-badges {\r
  98   float: right;\r
  99   padding-bottom: 0.5em;\r
 100 }\r
 101 \r
 102 div#preamble,\r
 103 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,\r
 104 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
 105 div.admonitionblock {\r
 106   margin-right: 10%;\r
 107   margin-top: 1.5em;\r
 108   margin-bottom: 1.5em;\r
 109 }\r
 110 div.admonitionblock {\r
 111   margin-top: 2.5em;\r
 112   margin-bottom: 2.5em;\r
 113 }\r
 114 \r
 115 div.content { /* Block element content. */\r
 116   padding: 0;\r
 117 }\r
 118 \r
 119 /* Block element titles. */\r
 120 div.title, caption.title {\r
 121   font-family: sans-serif;\r
 122   font-weight: bold;\r
 123   text-align: left;\r
 124   margin-top: 1.0em;\r
 125   margin-bottom: 0.5em;\r
 126 }\r
 127 div.title + * {\r
 128   margin-top: 0;\r
 129 }\r
 130 \r
 131 td div.title:first-child {\r
 132   margin-top: 0.0em;\r
 133 }\r
 134 div.content div.title:first-child {\r
 135   margin-top: 0.0em;\r
 136 }\r
 137 div.content + div.title {\r
 138   margin-top: 0.0em;\r
 139 }\r
 140 \r
 141 div.sidebarblock > div.content {\r
 142   background: #ffffee;\r
 143   border: 1px solid silver;\r
 144   padding: 0.5em;\r
 145 }\r
 146 \r
 147 div.listingblock {\r
 148   margin-right: 0%;\r
 149 }\r
 150 div.listingblock > div.content {\r
 151   border: 1px solid silver;\r
 152   background: #f4f4f4;\r
 153   padding: 0.5em;\r
 154 }\r
 155 \r
 156 div.quoteblock > div.content {\r
 157   padding-left: 2.0em;\r
 158 }\r
 159 \r
 160 div.attribution {\r
 161   text-align: right;\r
 162 }\r
 163 div.verseblock + div.attribution {\r
 164   text-align: left;\r
 165 }\r
 166 \r
 167 div.admonitionblock .icon {\r
 168   vertical-align: top;\r
 169   font-size: 1.1em;\r
 170   font-weight: bold;\r
 171   text-decoration: underline;\r
 172   color: #527bbd;\r
 173   padding-right: 0.5em;\r
 174 }\r
 175 div.admonitionblock td.content {\r
 176   padding-left: 0.5em;\r
 177   border-left: 2px solid silver;\r
 178 }\r
 179 \r
 180 div.exampleblock > div.content {\r
 181   border-left: 2px solid silver;\r
 182   padding: 0.5em;\r
 183 }\r
 184 \r
 185 div.verseblock div.content {\r
 186   white-space: pre;\r
 187 }\r
 188 \r
 189 div.imageblock div.content { padding-left: 0; }\r
 190 div.imageblock img { border: 1px solid silver; }\r
 191 span.image img { border-style: none; }\r
 192 \r
 193 dl {\r
 194   margin-top: 0.8em;\r
 195   margin-bottom: 0.8em;\r
 196 }\r
 197 dt {\r
 198   margin-top: 0.5em;\r
 199   margin-bottom: 0;\r
 200   font-style: italic;\r
 201 }\r
 202 dd > *:first-child {\r
 203   margin-top: 0;\r
 204 }\r
 205 \r
 206 ul, ol {\r
 207     list-style-position: outside;\r
 208 }\r
 209 ol.olist2 {\r
 210   list-style-type: lower-alpha;\r
 211 }\r
 212 \r
 213 div.tableblock > table {\r
 214   border: 3px solid #527bbd;\r
 215 }\r
 216 thead {\r
 217   font-family: sans-serif;\r
 218   font-weight: bold;\r
 219 }\r
 220 tfoot {\r
 221   font-weight: bold;\r
 222 }\r
 223 \r
 224 div.hlist {\r
 225   margin-top: 0.8em;\r
 226   margin-bottom: 0.8em;\r
 227 }\r
 228 div.hlist td {\r
 229   padding-bottom: 5px;\r
 230 }\r
 231 td.hlist1 {\r
 232   vertical-align: top;\r
 233   font-style: italic;\r
 234   padding-right: 0.8em;\r
 235 }\r
 236 td.hlist2 {\r
 237   vertical-align: top;\r
 238 }\r
 239 \r
 240 @media print {\r
 241   div#footer-badges { display: none; }\r
 242 }\r
 243 \r
 244 div#toctitle {\r
 245   color: #527bbd;\r
 246   font-family: sans-serif;\r
 247   font-size: 1.1em;\r
 248   font-weight: bold;\r
 249   margin-top: 1.0em;\r
 250   margin-bottom: 0.1em;\r
 251 }\r
 252 \r
 253 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {\r
 254   margin-top: 0;\r
 255   margin-bottom: 0;\r
 256 }\r
 257 div.toclevel2 {\r
 258   margin-left: 2em;\r
 259   font-size: 0.9em;\r
 260 }\r
 261 div.toclevel3 {\r
 262   margin-left: 4em;\r
 263   font-size: 0.9em;\r
 264 }\r
 265 div.toclevel4 {\r
 266   margin-left: 6em;\r
 267   font-size: 0.9em;\r
 268 }\r
 269 /* Workarounds for IE6's broken and incomplete CSS2. */\r
 270 \r
 271 div.sidebar-content {\r
 272   background: #ffffee;\r
 273   border: 1px solid silver;\r
 274   padding: 0.5em;\r
 275 }\r
 276 div.sidebar-title, div.image-title {\r
 277   font-family: sans-serif;\r
 278   font-weight: bold;\r
 279   margin-top: 0.0em;\r
 280   margin-bottom: 0.5em;\r
 281 }\r
 282 \r
 283 div.listingblock div.content {\r
 284   border: 1px solid silver;\r
 285   background: #f4f4f4;\r
 286   padding: 0.5em;\r
 287 }\r
 288 \r
 289 div.quoteblock-content {\r
 290   padding-left: 2.0em;\r
 291 }\r
 292 \r
 293 div.exampleblock-content {\r
 294   border-left: 2px solid silver;\r
 295   padding-left: 0.5em;\r
 296 }\r
 297 \r
 298 /* IE6 sets dynamically generated links as visited. */\r
 299 div#toc a:visited { color: blue; }\r
 300 </style>\r
 301 <script type="text/javascript">\r
 302 /*<![CDATA[*/\r
 303 window.onload = function(){generateToc(2)}\r
 304 /* Author: Mihai Bazon, September 2002\r
 305  * http://students.infoiasi.ro/~mishoo\r
 306  *\r
 307  * Table Of Content generator\r
 308  * Version: 0.4\r
 309  *\r
 310  * Feel free to use this script under the terms of the GNU General Public\r
 311  * License, as long as you do not remove or alter this notice.\r
 312  */\r
 313 \r
 314  /* modified by Troy D. Hanson, September 2006. License: GPL */\r
 315  /* modified by Stuart Rackham, October 2006. License: GPL */\r
 316 \r
 317 function getText(el) {\r
 318   var text = "";\r
 319   for (var i = el.firstChild; i != null; i = i.nextSibling) {\r
 320     if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.\r
 321       text += i.data;\r
 322     else if (i.firstChild != null)\r
 323       text += getText(i);\r
 324   }\r
 325   return text;\r
 326 }\r
 327 \r
 328 function TocEntry(el, text, toclevel) {\r
 329   this.element = el;\r
 330   this.text = text;\r
 331   this.toclevel = toclevel;\r
 332 }\r
 333 \r
 334 function tocEntries(el, toclevels) {\r
 335   var result = new Array;\r
 336   var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');\r
 337   // Function that scans the DOM tree for header elements (the DOM2\r
 338   // nodeIterator API would be a better technique but not supported by all\r
 339   // browsers).\r
 340   var iterate = function (el) {\r
 341     for (var i = el.firstChild; i != null; i = i.nextSibling) {\r
 342       if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {\r
 343         var mo = re.exec(i.tagName)\r
 344         if (mo)\r
 345           result[result.length] = new TocEntry(i, getText(i), mo[1]-1);\r
 346         iterate(i);\r
 347       }\r
 348     }\r
 349   }\r
 350   iterate(el);\r
 351   return result;\r
 352 }\r
 353 \r
 354 // This function does the work. toclevels = 1..4.\r
 355 function generateToc(toclevels) {\r
 356   var toc = document.getElementById("toc");\r
 357   var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);\r
 358   for (var i = 0; i < entries.length; ++i) {\r
 359     var entry = entries[i];\r
 360     if (entry.element.id == "")\r
 361       entry.element.id = "toc" + i;\r
 362     var a = document.createElement("a");\r
 363     a.href = "#" + entry.element.id;\r
 364     a.appendChild(document.createTextNode(entry.text));\r
 365     var div = document.createElement("div");\r
 366     div.appendChild(a);\r
 367     div.className = "toclevel" + entry.toclevel;\r
 368     toc.appendChild(div);\r
 369   }\r
 370 }\r
 371 /*]]>*/\r
 372 </script>\r
 373 <title>grml policy</title>\r
 374 </head>\r
 375 <body>\r
 376 <div id="header">\r
 377 <h1>grml policy</h1>\r
 378 <div id="toc">\r
 379   <div id="toctitle">Table of Contents</div>\r
 380   <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>\r
 381 </div>\r
 382 </div>\r
 383 <div id="preamble">\r
 384 <div class="sectionbody">\r
 385 <div class="sidebarblock">\r
 386 <div class="sidebar-content">\r
 387 <p>Important! This file is not yet official - work in progress.</p>\r
 388 </div></div>\r
 389 </div>\r
 390 </div>\r
 391 <h2>1. Preface</h2>\r
 392 <div class="sectionbody">\r
 393 <p>This is a short documentation describing different policies used at and for\r
 394 <a href="http://grml.org/">grml</a>.</p>\r
 395 </div>\r
 396 <h2>2. Packaging Software</h2>\r
 397 <div class="sectionbody">\r
 398 <p>If you are not yet familiar with <strong>creating</strong> Debian packaging useful\r
 399 resources are the <a href="http://www.debian.org/doc/maint-guide/">Debian New\r
 400 Maintainers' Guide</a> and\r
 401 <a href="http://www.debian.org/doc/manuals/developers-reference/index.en.html">The\r
 402 Debian Developer's Reference</a>.</p>\r
 403 <p>Software that should be <strong>added</strong> to the grml repository (and as a\r
 404 consequence being available for inclusion in grml) must be packaged\r
 405 according to the\r
 406 <a href="http://www.debian.org/doc/debian-policy/index.html">Debian policy</a>.\r
 407 The Debian packages should be\r
 408 <a href="http://lintian.debian.org/">lintian</a>-clean and have to provide manpages\r
 409 for the shipped executables. The package should be maintained inside a\r
 410 mercurial repository hosted at <a href="http://hg.grml.org/">hg.grml.org</a>.\r
 411 If the package is a grml specific package (so upstream is different from\r
 412 the grml-team) the Debian package has to start with the suffix <em>grml-</em> (so\r
 413 the grml specific packages can be identified easily).</p>\r
 414 <p>If you want to see software included in grml but won't be able to deal with\r
 415 the Debian package please <a href="http://grml.org/report/">send your feature\r
 416 request to the grml-team</a>.</p>\r
 417 <p>Uploading Debian packages to <a href="http://deb.grml.org/">the grml pool</a> is\r
 418 restricted to the ftp-masters (being Michael Prokop and Alexander Wirt at\r
 419 the time of writing this document).</p>\r
 420 <p>As a long term goal the Debian packages used at grml should be provided to\r
 421 the official Debian distribution using the official\r
 422 <a href="http://www.debian.org/devel/wnpp/">WNPP / ITP (Intend To Package)</a>\r
 423 procedure.</p>\r
 424 </div>\r
 425 <h2>3. Adding Software to grml</h2>\r
 426 <div class="sectionbody">\r
 427 <p>If you plan to write software for inclusion and distribution by grml you\r
 428 should be aware of the following requirements:</p>\r
 429 <ul>\r
 430 <li>\r
 431 <p>\r
 432 The software has to be licensed under an\r
 433 <a href="http://www.opensource.org/licenses">OSI approved license</a> and should\r
 434 follow the <a href="http://www.debian.org/social_contract#guidelines">The Debian\r
 435 Free Software Guidelines (DFSG)</a>. The grml-team prefers the\r
 436 <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License\r
 437 (GPL)</a>. If you want to see your patch/script/software included in a core\r
 438 grml package it has to be licensed under the GPL as well.\r
 439 </p>\r
 440 </li>\r
 441 <li>\r
 442 <p>\r
 443 Your software has to provide documentation. The package must provide at\r
 444 least an up2date manpage. The grml-team prefers documentation written in\r
 445 <a href="http://www.methods.co.nz/asciidoc/">asciidoc</a>, see\r
 446 <a href="http://grml.org/docs/">grml.org/docs/</a> and\r
 447 <a href="http://hg.grml.org/grml-debootstrap/file/tip/grml-debootstrap.8.txt">grml-debootstrap.8.txt</a>\r
 448 for a real-life example.\r
 449 </p>\r
 450 </li>\r
 451 <li>\r
 452 <p>\r
 453 Your software should be as platform independent as possible and should\r
 454 work at least on x86, x86_64 (amd64) and ppc.\r
 455 </p>\r
 456 </li>\r
 457 </ul>\r
 458 </div>\r
 459 <h2>4. Contributing patches to grml</h2>\r
 460 <div class="sectionbody">\r
 461 <p>Software written by and maintained by the grml-team is available at\r
 462 <a href="http://hg.grml.org/">hg.grml.org</a>. If you plan to provide a patch to\r
 463 the grml-team you can checkout the according repository and create a patch\r
 464 using the <em>hg diff</em> command. Usage example:</p>\r
 465 <div class="listingblock">\r
 466 <div class="content"><!-- Generator: GNU source-highlight 2.4\r
 467 by Lorenzo Bettini\r
 468 http://www.lorenzobettini.it\r
 469 http://www.gnu.org/software/src-highlite -->\r
 470 <pre><tt>hg clone http<span style="color: #990000">:</span>//hg<span style="color: #990000">.</span>grml<span style="color: #990000">.</span>org/grml-policy\r
 471 cd grml-policy\r
 472 hg diff <span style="color: #990000">&gt;</span> update_for_grml-policy-mention_foobar<span style="color: #990000">.</span>diff\r
 473 </tt></pre></div></div>\r
 474 <p>And mail the resulting diff to the grml-team. The maintainer of the\r
 475 according repository is listed in the Contact-column on\r
 476 <a href="http://hg.grml.org/">hg.grml.org</a>. You are free to\r
 477 <a href="http://grml.org/contact/">contact the grml-team directly via mail</a> or\r
 478 the <a href="http://grml.org/mailinglist/">grml-mailinglist</a> as well.</p>\r
 479 <p>More details regarding use of mercurial at grml is available at\r
 480 <a href="http://grml.org/mercurial/">grml.org/mercurial/</a>.</p>\r
 481 </div>\r
 482 <h2>5. Common practices for writing code</h2>\r
 483 <div class="sectionbody">\r
 484 <h3>5.1. Header information</h3>\r
 485 <p>Every script should provide a header which should look like this:</p>\r
 486 <div class="literalblock">\r
 487 <div class="content">\r
 488 <pre><tt>#!/bin/sh\r
 489 # Filename:      grml2hd\r
 490 # Purpose:       install grml to harddisk\r
 491 # Authors:       grml-team (grml.org), (c) Andreas Gredler &lt;jimmy@grml.org&gt;, Michael Prokop &lt;mika@grml.org&gt;\r
 492 # Bug-Reports:   see http://grml.org/bugs/\r
 493 # License:       This file is licensed under the GPL v2.\r
 494 # Latest change: Thu Sep 13 23:00:56 CEST 2007 [mika]\r
 495 ################################################################################</tt></pre>\r
 496 </div></div>\r
 497 <h3>5.2. Footer information</h3>\r
 498 <p>Most developers of the grml-team use Vim as their favourite editor.\r
 499 Therefor providing a modeline at the end of the sourcefile is commonly used\r
 500 to indicate the favourite editing mode/style. Usage example:</p>\r
 501 <div class="literalblock">\r
 502 <div class="content">\r
 503 <pre><tt># vim: ai filetype=sh expandtab shiftwidth=3</tt></pre>\r
 504 </div></div>\r
 505 <h3>5.3. grml shellscript library</h3>\r
 506 <p>The grml system provides several shellscript resources. The package\r
 507 grml-etc-core provides the files /etc/grml/lsb-functions and\r
 508 /etc/grml/script-functions, the package grml-shlib ships /etc/grml/sh-lib.</p>\r
 509 <h4>5.3.1. /etc/grml/lsb-functions</h4>\r
 510 <p>The file /etc/grml/lsb-functions is used within init-scripts and init-style\r
 511 scripts (like shellscripts handling with services) and is supposed to be\r
 512 POSIX-compatible. Usage example:</p>\r
 513 <div class="listingblock">\r
 514 <div class="content"><!-- Generator: GNU source-highlight 2.4\r
 515 by Lorenzo Bettini\r
 516 http://www.lorenzobettini.it\r
 517 http://www.gnu.org/software/src-highlite -->\r
 518 <pre><tt><span style="color: #990000">%</span> <span style="font-weight: bold"><span style="color: #0000FF">source</span></span> /etc/grml/lsb-functions\r
 519 <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: #990000">?</span>\r
 520  <span style="color: #990000">*</span> Starting foobar<span style="color: #990000">.</span>                                  <span style="color: #990000">[</span> ok <span style="color: #990000">]</span>\r
 521 <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: #990000">?</span>\r
 522  <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
 523 <span style="color: #990000">%</span>\r
 524 </tt></pre></div></div>\r
 525 <p>If you want to provide output on the plain console (without using an\r
 526 interface like <a href="http://invisible-island.net/dialog/">dialog</a> or\r
 527 <a href="http://www.clifford.at/stfl/">stfl</a>) you should consider the use of\r
 528 /etc/grml/lsb-functions so look and feel of grml-scripts is as consistent\r
 529 as possible.</p>\r
 530 <h4>5.3.2. /etc/grml/script-functions</h4>\r
 531 <p>The file /etc/grml/script-functions provides common functions used inside\r
 532 several scripts, like check4root (check for root-permissions), iszsh (check\r
 533 for running zsh). The file is supposed to be used in every POSIX-compatible\r
 534 shell (otherwise it's a bug).</p>\r
 535 <h4>5.3.3. /etc/grml/sh-lib</h4>\r
 536 <p>The file /etc/grml/sh-lib provides a smiliar functionality like\r
 537 /etc/grml/lsb-functions and /etc/grml/script-functions do. As a long term\r
 538 goal the functionality of this file should be merged with the one of\r
 539 lsb-functions and script-functions.</p>\r
 540 <h3>5.4. Good practices for shellscript</h3>\r
 541 <ul>\r
 542 <li>\r
 543 <p>\r
 544 <strong>shebang line:</strong> if you use <em>#!/bin/sh</em> as the shebang line of your\r
 545 shellscript you should make sure that the script runs under every\r
 546 POSIX-compatible shell. A good test is the use of /bin/dash for /bin/sh. If\r
 547 you use bash/zsh/ksh93/&#8230;  specific features please use the according\r
 548 shell in the shebang line of your script.\r
 549 </p>\r
 550 </li>\r
 551 <li>\r
 552 <p>\r
 553 <strong>check for appropriate permissions:</strong> if you need root permissions you\r
 554 should make sure that your script is running as user root (take a look at\r
 555 check4root function provided by /etc/grml/script-functions).\r
 556 </p>\r
 557 </li>\r
 558 <li>\r
 559 <p>\r
 560 <strong>clean up when being interrupted and on exit:</strong> your script should not leave\r
 561 any temporary files (unless intented for debugging purposes of course).\r
 562 Usage example:\r
 563 </p>\r
 564 <div class="listingblock">\r
 565 <div class="content"><!-- Generator: GNU source-highlight 2.4\r
 566 by Lorenzo Bettini\r
 567 http://www.lorenzobettini.it\r
 568 http://www.gnu.org/software/src-highlite -->\r
 569 <pre><tt><span style="color: #009900">TMPFILE</span><span style="color: #990000">=</span><span style="color: #009900">$(mktemp</span> <span style="color: #009900">${TMP}</span>/grml2hd<span style="color: #990000">.</span>XXXXXX<span style="color: #990000">)</span>\r
 570 <span style="font-weight: bold"><span style="color: #000000">bailout()</span></span> {\r
 571   rm -f <span style="color: #FF0000">"$TMPFILE"</span>\r
 572   <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
 573   <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span> <span style="color: #FF0000">"$EXIT"</span>\r
 574 }\r
 575 <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
 576 <span style="color: #009900">$CODE</span>\r
 577 bailout <span style="color: #993399">0</span>\r
 578 </tt></pre></div></div>\r
 579 </li>\r
 580 <li>\r
 581 <p>\r
 582 <strong>use of subshells:</strong> please use <em>$(&#8230;)</em> instead of <em>`&#8230;`</em>.\r
 583 </p>\r
 584 <p>It allows nesting of commands in a more clearly and easier way.\r
 585 Therefore any shell code might appear within the parentheses, since\r
 586 the only time parentheses occur unquoted is in pairs.<br />\r
 587 With backquotes however any unquoted <em>`</em> within the form <em>`&#8230;`</em>\r
 588 would end the quotes immediately.</p>\r
 589 <p>Consider the following as an example on readability:</p>\r
 590 <div class="listingblock">\r
 591 <div class="content"><!-- Generator: GNU source-highlight 2.4\r
 592 by Lorenzo Bettini\r
 593 http://www.lorenzobettini.it\r
 594 http://www.gnu.org/software/src-highlite -->\r
 595 <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
 596 <span style="color: #990000">%</span> echo <span style="color: #FF0000">"Tomorrow's date: $(expr $(date +%d) + 1).$(date +%m)."</span>\r
 597 </tt></pre></div></div>\r
 598 <p>Furthermore it can get quite tricky to get the right level of quotes\r
 599 when using backquotes.</p>\r
 600 <div class="listingblock">\r
 601 <div class="content"><!-- Generator: GNU source-highlight 2.4\r
 602 by Lorenzo Bettini\r
 603 http://www.lorenzobettini.it\r
 604 http://www.gnu.org/software/src-highlite -->\r
 605 <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
 606 hello\r
 607 <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
 608 <span style="color: #FF0000">"hello"</span>\r
 609 </tt></pre></div></div>\r
 610 <p>For further reading have a look at\r
 611 <a href="http://zsh.dotsrc.org/Guide/zshguide05.html#l11">A User's Guide to the\r
 612 Z Shell</a>\r
 613 and <a href="http://zsh.sourceforge.net/Intro/intro_7.html#SEC7">Introduction to\r
 614 the Z Shell</a></p>\r
 615 </li>\r
 616 <li>\r
 617 <p>\r
 618 <strong>if &#8230; then &#8230; else &#8230;</strong>: you should make sure that the code is as\r
 619 easy understandable as possible. So instead of using:\r
 620 </p>\r
 621 <div class="listingblock">\r
 622 <div class="content"><!-- Generator: GNU source-highlight 2.4\r
 623 by Lorenzo Bettini\r
 624 http://www.lorenzobettini.it\r
 625 http://www.gnu.org/software/src-highlite -->\r
 626 <pre><tt><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
 627    foo\r
 628    bar\r
 629    bla\r
 630 <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>\r
 631    baz\r
 632 <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>\r
 633 \r
 634 you should consider use of<span style="color: #990000">:</span>\r
 635 \r
 636 <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -z <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
 637    baz\r
 638 <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>\r
 639    foo\r
 640    bar\r
 641    bla\r
 642 <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>\r
 643 </tt></pre></div></div>\r
 644 </li>\r
 645 <li>\r
 646 <p>\r
 647 <strong>indenting:</strong> make sure you indent your code and use blank lines where\r
 648 according. Commonly accepted textwidth is 80 chars. (TODO: provide some\r
 649 more information&#8230;)\r
 650 </p>\r
 651 </li>\r
 652 <li>\r
 653 <p>\r
 654 <strong>use of tabs:</strong> the grml-team prefers to <strong>not</strong> use any tabs inside\r
 655 their code. Please use 4 spaces instead of a tab instead (<em>tabstop=4</em> and\r
 656 <em>set expandtab</em> when using Vim editor). To replace tabs with spaces you can\r
 657 use <em>:set expandtab</em> and <em>:retab</em> using Vim editor.\r
 658 </p>\r
 659 </li>\r
 660 <li>\r
 661 <p>\r
 662 <strong>no trailing whitespaces:</strong> make sure your code does not contain any\r
 663 trailing whitespaces. Remove them inside Vim editor running <em>:%s/\s+$//</em>\r
 664 and make them visible using for example <em>:set\r
 665 listchars=eol:$,precedes:«,extends:»,tab:»·,trail:·</em>.\r
 666 </p>\r
 667 </li>\r
 668 </ul>\r
 669 </div>\r
 670 <h2>6. About this document</h2>\r
 671 <div class="sectionbody">\r
 672 <p>&#169; Michael Prokop &lt;mika@grml.org&gt;; HTML version powered by <a href="http://www.methods.co.nz/asciidoc/">asciidoc</a>.</p>\r
 673 </div>\r
 674 <div id="footer">\r
 675 <div id="footer-text">\r
 676 Last updated 17-Dec-2007 04:31:59 CEST\r
 677 </div>\r
 678 </div>\r
 679 </body>\r
 680 </html>\r