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
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
10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
\r
12 border: 1px solid red;
\r
17 margin: 1em 5% 1em 5%;
\r
22 text-decoration: underline;
\r
42 h1, h2, h3, h4, h5, h6 {
\r
44 font-family: sans-serif;
\r
46 margin-bottom: 0.5em;
\r
51 border-bottom: 2px solid silver;
\r
69 border: 1px solid silver;
\r
74 margin-bottom: 0.5em;
\r
88 font-family: sans-serif;
\r
94 span#revnumber, span#revdate, span#revremark {
\r
95 font-family: sans-serif;
\r
99 font-family: sans-serif;
\r
101 border-top: 2px solid silver;
\r
102 padding-top: 0.5em;
\r
107 padding-bottom: 0.5em;
\r
109 div#footer-badges {
\r
111 padding-bottom: 0.5em;
\r
116 margin-bottom: 1.5em;
\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
122 margin-bottom: 1.5em;
\r
124 div.admonitionblock {
\r
126 margin-bottom: 2.0em;
\r
131 div.content { /* Block element content. */
\r
135 /* Block element titles. */
\r
136 div.title, caption.title {
\r
138 font-family: sans-serif;
\r
142 margin-bottom: 0.5em;
\r
148 td div.title:first-child {
\r
151 div.content div.title:first-child {
\r
154 div.content + div.title {
\r
158 div.sidebarblock > div.content {
\r
159 background: #ffffee;
\r
160 border: 1px solid silver;
\r
164 div.listingblock > div.content {
\r
165 border: 1px solid silver;
\r
166 background: #f4f4f4;
\r
170 div.quoteblock, div.verseblock {
\r
171 padding-left: 1.0em;
\r
172 margin-left: 1.0em;
\r
174 border-left: 5px solid #dddddd;
\r
178 div.quoteblock > div.attribution {
\r
179 padding-top: 0.5em;
\r
183 div.verseblock > div.content {
\r
186 div.verseblock > div.attribution {
\r
187 padding-top: 0.75em;
\r
190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
\r
191 div.verseblock + div.attribution {
\r
195 div.admonitionblock .icon {
\r
196 vertical-align: top;
\r
199 text-decoration: underline;
\r
201 padding-right: 0.5em;
\r
203 div.admonitionblock td.content {
\r
204 padding-left: 0.5em;
\r
205 border-left: 3px solid #dddddd;
\r
208 div.exampleblock > div.content {
\r
209 border-left: 3px solid #dddddd;
\r
210 padding-left: 0.5em;
\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
219 margin-bottom: 0.8em;
\r
224 font-style: normal;
\r
227 dd > *:first-child {
\r
232 list-style-position: outside;
\r
235 list-style-type: decimal;
\r
238 list-style-type: lower-alpha;
\r
241 list-style-type: upper-alpha;
\r
244 list-style-type: lower-roman;
\r
247 list-style-type: upper-roman;
\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
254 margin-bottom: 0.1em;
\r
257 div.tableblock > table {
\r
258 border: 3px solid #527bbd;
\r
260 thead, p.table.header {
\r
261 font-family: sans-serif;
\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
277 div.tableblock > table[frame="hsides"] {
\r
278 border-left-style: none;
\r
279 border-right-style: none;
\r
281 div.tableblock > table[frame="vsides"] {
\r
282 border-top-style: none;
\r
283 border-bottom-style: none;
\r
289 margin-bottom: 0.8em;
\r
292 padding-bottom: 15px;
\r
294 dt.hdlist1.strong, td.hdlist1.strong {
\r
298 vertical-align: top;
\r
299 font-style: normal;
\r
300 padding-right: 0.8em;
\r
304 vertical-align: top;
\r
306 div.hdlist.compact tr {
\r
312 background: yellow;
\r
315 .footnote, .footnoteref {
\r
319 span.footnote, span.footnoteref {
\r
320 vertical-align: super;
\r
324 margin: 20px 0 20px 0;
\r
325 padding: 7px 0 0 0;
\r
328 #footnotes div.footnote {
\r
334 border-top: 1px solid silver;
\r
344 div#footer-badges { display: none; }
\r
348 margin-bottom: 2.5em;
\r
353 font-family: sans-serif;
\r
357 margin-bottom: 0.1em;
\r
360 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
\r
376 /* Workarounds for IE6's broken and incomplete CSS2. */
\r
378 div.sidebar-content {
\r
379 background: #ffffee;
\r
380 border: 1px solid silver;
\r
383 div.sidebar-title, div.image-title {
\r
385 font-family: sans-serif;
\r
388 margin-bottom: 0.5em;
\r
391 div.listingblock div.content {
\r
392 border: 1px solid silver;
\r
393 background: #f4f4f4;
\r
397 div.quoteblock-attribution {
\r
398 padding-top: 0.5em;
\r
402 div.verseblock-content {
\r
405 div.verseblock-attribution {
\r
406 padding-top: 0.75em;
\r
410 div.exampleblock-content {
\r
411 border-left: 3px solid #dddddd;
\r
412 padding-left: 0.5em;
\r
415 /* IE6 sets dynamically generated links as visited. */
\r
416 div#toc a:visited { color: blue; }
\r
418 <script type="text/javascript">
\r
420 window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
\r
421 var asciidoc = { // Namespace.
\r
423 /////////////////////////////////////////////////////////////////////
\r
424 // Table Of Contents generator
\r
425 /////////////////////////////////////////////////////////////////////
\r
427 /* Author: Mihai Bazon, September 2002
\r
428 * http://students.infoiasi.ro/~mishoo
\r
430 * Table Of Content generator
\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
437 /* modified by Troy D. Hanson, September 2006. License: GPL */
\r
438 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
\r
440 // toclevels = 1..4.
\r
441 toc: function (toclevels) {
\r
443 function getText(el) {
\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
448 else if (i.firstChild != null)
\r
449 text += getText(i);
\r
454 function TocEntry(el, text, toclevel) {
\r
457 this.toclevel = toclevel;
\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
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
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
495 if (entries.length == 0)
\r
496 toc.parentNode.removeChild(toc);
\r
500 /////////////////////////////////////////////////////////////////////
\r
501 // Footnotes generator
\r
502 /////////////////////////////////////////////////////////////////////
\r
504 /* Based on footnote generation code from:
\r
505 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
\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
514 for (i=0; i<spans.length; i++) {
\r
515 if (spans[i].className == "footnote") {
\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
532 noteholder.parentNode.removeChild(noteholder);
\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
540 spans[i].innerHTML =
\r
541 "[<a href='#_footnote_" + n +
\r
542 "' title='View footnote' class='footnote'>" + n + "</a>]";
\r
554 <h1>grml policy</h1>
\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
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
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
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’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
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’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
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
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
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
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
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
647 <div class="listingblock">
\r
648 <div class="content"><!-- Generator: GNU source-highlight 3.1.3
\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
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
675 # Filename: grml2hd
\r
676 # Purpose: install grml to harddisk
\r
677 # Authors: grml-team (grml.org), (c) Andreas Gredler <jimmy@grml.org>, Michael Prokop <mika@grml.org>
\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
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
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
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’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
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/… specific features please use the according
\r
733 shell in the shebang line of your script.
\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
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
749 <div class="listingblock">
\r
750 <div class="content"><!-- Generator: GNU source-highlight 3.1.3
\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">&&</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
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
766 <strong>use of subshells:</strong> please use <em>$(…)</em> instead of <em>`…\`</em>.
\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 _\`…\`</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
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
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
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’s Guide to the
\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
800 <strong>if … then … else … etc.</strong>: Use the coding style used in other
\r
801 shell scripts shipped by grml, like:
\r
803 <div class="listingblock">
\r
804 <div class="content"><!-- Generator: GNU source-highlight 3.1.3
\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
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
812 <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
\r
814 <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
\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
818 <span style="font-weight: bold"><span style="color: #0000FF">done</span></span>
\r
820 <span style="font-style: italic"><span style="color: #9A1900">## instead of these:</span></span>
\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
825 <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
\r
827 <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
\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
832 <span style="font-weight: bold"><span style="color: #0000FF">done</span></span></tt></pre></div></div>
\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…)
\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
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
859 <h2 id="_about_this_document">6. About this document</h2>
\r
860 <div class="sectionbody">
\r
861 <div class="paragraph"><p>© Michael Prokop <<a href="mailto:mika@grml.org">mika@grml.org</a>>; HTML version powered by <a href="http://www.methods.co.nz/asciidoc/">asciidoc</a>.</p></div>
\r
864 <div id="footnotes"><hr /></div>
\r
866 <div id="footer-text">
\r
867 Last updated 2010-02-28 01:48:56 CEST
\r