Git commit 4656463e1a61a7c1fefd65483d3d10c2b6fb2881 by Carl Schwan, on behalf of Sebastian Engel. Committed on 18/09/2020 at 16:05. Pushed by carlschwan into branch 'master'.
Document BasKet archive file format This commit adds some explanations to the archive format of BasKet (.baskets), Such as the file header, and the contained files. A +- -- doc/basket-archive-file-content-example.png A +527 -0 doc/basket-archive-file-content-example.svg A +- -- doc/basket-archive-file-structure.png A +208 -0 doc/basket-archive-file-structure.svg M +198 -115 doc/index.docbook https://invent.kde.org/utilities/basket/commit/4656463e1a61a7c1fefd65483d3d10c2b6fb2881 diff --git a/doc/basket-archive-file-content-example.png b/doc/basket-archive-file-content-example.png new file mode 100644 index 0000000..ebeb868 Binary files /dev/null and b/doc/basket-archive-file-content-example.png differ diff --git a/doc/basket-archive-file-content-example.svg b/doc/basket-archive-file-content-example.svg new file mode 100644 index 0000000..281c944 --- /dev/null +++ b/doc/basket-archive-file-content-example.svg @@ -0,0 +1,527 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/"; + xmlns:cc="http://creativecommons.org/ns#"; + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"; + xmlns:svg="http://www.w3.org/2000/svg"; + xmlns="http://www.w3.org/2000/svg"; + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"; + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"; + inkscape:export-ydpi="200" + inkscape:export-xdpi="200" + inkscape:export-filename="basket-archive-file-content-example.png" + sodipodi:docname="basket-archive-file-content-example.svg" + inkscape:version="1.0 (4035a4fb49, 2020-05-01)" + id="svg1201" + version="1.1" + viewBox="0 0 163.55641 56.65419" + height="56.65419mm" + width="163.55641mm"> + <defs + id="defs1195"> + <rect + id="rect1862" + height="7.4395375" + width="178.24802" + y="4.4020014" + x="-5.0409842" /> + <rect + id="rect1790" + height="8.2868271" + width="138.05174" + y="7.792882e-07" + x="27.499769" /> + <rect + id="rect1778" + height="7.722013" + width="20.037434" + y="7.792882e-07" + x="-0.037433885" /> + <rect + x="-0.037433885" + y="7.792882e-07" + width="20.037434" + height="7.722013" + id="rect1810" /> + <rect + x="27.499769" + y="7.792882e-07" + width="56.142651" + height="7.2459455" + id="rect1812" /> + <rect + x="-0.037433885" + y="7.792882e-07" + width="20.037434" + height="7.722013" + id="rect1832" /> + <rect + x="27.499769" + y="7.792882e-07" + width="56.142651" + height="7.2459455" + id="rect1834" /> + <rect + x="27.499769" + y="7.792882e-07" + width="138.05174" + height="8.2868271" + id="rect1844" /> + <rect + x="-0.037433885" + y="7.792882e-07" + width="20.037434" + height="7.722013" + id="rect1850" /> + <rect + id="rect1914" + height="7.722013" + width="20.037434" + y="7.792882e-07" + x="-0.037433885" /> + <rect + id="rect1916" + height="8.2868271" + width="138.05174" + y="7.792882e-07" + x="27.499769" /> + <rect + x="-0.037433885" + y="7.792882e-07" + width="20.037434" + height="7.722013" + id="rect1932" /> + <rect + x="27.499769" + y="7.792882e-07" + width="138.05174" + height="8.2868271" + id="rect1934" /> + <rect + id="rect1966" + height="7.722013" + width="20.037434" + y="7.792882e-07" + x="-0.037433885" /> + <rect + id="rect1968" + height="8.2868271" + width="138.05174" + y="7.792882e-07" + x="27.499769" /> + <rect + x="-0.037433885" + y="7.792882e-07" + width="20.037434" + height="7.722013" + id="rect1984" /> + <rect + x="27.499769" + y="7.792882e-07" + width="138.05174" + height="8.2868271" + id="rect1986" /> + <rect + id="rect2015" + height="7.722013" + width="20.037434" + y="7.792882e-07" + x="-0.037433885" /> + <rect + id="rect2017" + height="8.2868271" + width="138.05174" + y="7.792882e-07" + x="27.499769" /> + <rect + x="-0.037433885" + y="7.792882e-07" + width="20.037434" + height="7.722013" + id="rect2027" /> + </defs> + <sodipodi:namedview + inkscape:window-maximized="1" + inkscape:window-y="0" + inkscape:window-x="0" + inkscape:window-height="2055" + inkscape:window-width="3840" + fit-margin-right="3" + fit-margin-left="3" + fit-margin-bottom="3" + fit-margin-top="3" + inkscape:snap-object-midpoints="true" + inkscape:object-paths="true" + inkscape:snap-midpoints="true" + inkscape:snap-intersection-paths="true" + inkscape:bbox-paths="true" + inkscape:snap-bbox-edge-midpoints="true" + inkscape:snap-bbox-midpoints="true" + inkscape:snap-bbox="true" + inkscape:guide-bbox="true" + showguides="true" + showgrid="false" + inkscape:document-rotation="0" + inkscape:current-layer="layer1" + inkscape:document-units="mm" + inkscape:cy="205.98454" + inkscape:cx="316.09927" + inkscape:zoom="2.8" + inkscape:pageshadow="2" + inkscape:pageopacity="0.0" + borderopacity="1.0" + bordercolor="#666666" + pagecolor="#ffffff" + id="base"> + <sodipodi:guide + inkscape:color="rgb(0,0,255)" + inkscape:locked="false" + inkscape:label="" + id="guide1764" + orientation="-1,0" + position="23.231704,35.479872" /> + <sodipodi:guide + inkscape:color="rgb(0,0,255)" + inkscape:locked="false" + inkscape:label="" + id="guide1766" + orientation="-1,0" + position="74.371765,32.128192" /> + <sodipodi:guide + inkscape:color="rgb(0,0,255)" + inkscape:locked="false" + inkscape:label="" + id="guide1768" + orientation="-1,0" + position="125.50495,52.841022" /> + <sodipodi:guide + inkscape:color="rgb(0,0,255)" + inkscape:locked="false" + inkscape:label="" + id="guide1770" + orientation="0,1" + position="23.231703,53.654192" /> + <sodipodi:guide + inkscape:color="rgb(0,0,255)" + inkscape:locked="false" + inkscape:label="" + id="guide1782" + orientation="-1,0" + position="13.231705,56.660981" /> + <sodipodi:guide + inkscape:color="rgb(0,0,255)" + inkscape:locked="false" + inkscape:label="" + id="guide1786" + orientation="0,1" + position="3.2317041,51.154192" /> + <sodipodi:guide + id="guide1946" + orientation="1,0" + position="144.11727,47.101212" /> + <sodipodi:guide + id="guide2021" + orientation="0,-1" + position="3,3.000001" /> + </sodipodi:namedview> + <metadata + id="metadata1198"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage"; /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + transform="translate(3.2317041,2.9999992)" + id="layer1" + inkscape:groupmode="layer" + inkscape:label="Layer 1"> + <path + sodipodi:nodetypes="cc" + id="path1772" + d="M 20.000001,7.7928822e-7 20,50.654191" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M 122.27324,7.7666667e-7 V 50.654191" + id="path1774" /> + <g + id="g1872"> + <text + xml:space="preserve" + id="text1776" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;line-height:1.25;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1778)" + x="8.1588526" + y="0" + transform="translate(-0.87846032,0.52378167)"><tspan + x="0.45488887" + y="3.1389396"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;text-anchor:middle">0000:0010</tspan></tspan></text> + <text + xml:space="preserve" + id="text1788" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1790);" + transform="translate(-6.0899225,0.51704028)"><tspan + x="27.5" + y="3.2438663"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono'">42 61 73 4b 65 74 4e 50 3a 61 72 63 68 69 76 65</tspan></tspan></text> + <text + xml:space="preserve" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + x="123.64199" + y="3.7609065" + id="text1796"><tspan + sodipodi:role="line" + id="tspan1794" + x="123.64199" + y="3.7609065" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';stroke-width:0.264583">BasKetNP:archive</tspan></text> + </g> + <g + id="g1880"> + <text + transform="translate(-0.87846032,4.2279485)" + y="0" + x="8.1588526" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;line-height:1.25;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1832)" + id="text1820" + xml:space="preserve"><tspan + x="0.45488887" + y="3.1389396"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;text-anchor:middle">0000:0020</tspan></tspan></text> + <text + transform="translate(-6.0899225,4.2212071)" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1844);" + id="text1838" + xml:space="preserve"><tspan + x="27.5" + y="3.2438663"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono'">0a 76 65 72 73 69 6f 6e 3a 30 2e 36 2e 31 0a 70</tspan></tspan></text> + <text + id="text1842" + y="7.4650731" + x="123.64199" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';stroke-width:0.264583" + y="7.4650731" + x="123.64199" + sodipodi:role="line" + id="tspan1854">·version:0.6.1·p</tspan></text> + </g> + <g + transform="translate(0,3.7041668)" + id="g1912"> + <text + xml:space="preserve" + id="text1902" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;line-height:1.25;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1914)" + x="8.1588526" + y="0" + transform="translate(-0.87846032,4.2279485)"><tspan + x="0.45488887" + y="3.1389396"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;text-anchor:middle">0000:0030</tspan></tspan></text> + <text + xml:space="preserve" + id="text1906" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1916);" + transform="translate(-6.0899225,4.2212071)"><tspan + x="27.5" + y="3.2438663"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono'">72 65 76 69 65 77 2a 3a 31 39 34 34 36 0a 89 50</tspan></tspan></text> + <text + xml:space="preserve" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + x="123.64199" + y="7.4650731" + id="text1910"><tspan + id="tspan1908" + sodipodi:role="line" + x="123.64199" + y="7.4650731" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';stroke-width:0.264583">review*:19446··P</tspan></text> + </g> + <g + id="g1930" + transform="translate(0,7.4083337)"> + <text + transform="translate(-0.87846032,4.2279485)" + y="0" + x="8.1588526" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;line-height:1.25;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1932)" + id="text1920" + xml:space="preserve"><tspan + x="0.45488887" + y="3.1389396"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;text-anchor:middle">0000:0030</tspan></tspan></text> + <text + transform="translate(-6.0899225,4.2212071)" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1934);" + id="text1924" + xml:space="preserve"><tspan + x="27.5" + y="3.2438663"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono'">4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52 00 00</tspan></tspan></text> + <text + id="text1928" + y="7.4650731" + x="123.64199" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';stroke-width:0.264583" + y="7.4650731" + x="123.64199" + sodipodi:role="line" + id="tspan1926">NG········IHDR··</tspan></text> + </g> + <g + id="g1991"> + <circle + style="fill:#000000;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:none;paint-order:stroke fill markers" + id="path1936" + cx="71.14006" + cy="17.321835" + r="0.5" /> + <circle + r="0.5" + cy="21.026005" + cx="71.14006" + id="circle1948" + style="fill:#000000;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:none;paint-order:stroke fill markers" /> + <circle + style="fill:#000000;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:none;paint-order:stroke fill markers" + id="circle1950" + cx="71.14006" + cy="24.730175" + r="0.5" /> + </g> + <g + transform="translate(0,22.225008)" + id="g1964"> + <text + xml:space="preserve" + id="text1954" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;line-height:1.25;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1966)" + x="8.1588526" + y="0" + transform="translate(-0.87846032,4.2279485)"><tspan + x="0.45488887" + y="3.1389396"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;text-anchor:middle">0000:4c20</tspan></tspan></text> + <text + xml:space="preserve" + id="text1958" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1968);" + transform="translate(-6.0899225,4.2212071)"><tspan + x="27.5" + y="3.2438663"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono'">ae 42 60 82 61 72 63 68 69 76 65 2a 3a 33 34 37</tspan></tspan></text> + <text + xml:space="preserve" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + x="123.64199" + y="7.4650731" + id="text1962"><tspan + id="tspan1960" + sodipodi:role="line" + x="123.64199" + y="7.4650731" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';stroke-width:0.264583">·B`·archive*:347</tspan></text> + </g> + <g + id="g1982" + transform="translate(0,25.929177)"> + <text + transform="translate(-0.87846032,4.2279485)" + y="0" + x="8.1588526" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;line-height:1.25;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1984)" + id="text1972" + xml:space="preserve"><tspan + x="0.45488887" + y="3.1389396"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;text-anchor:middle">0000:4c30</tspan></tspan></text> + <text + transform="translate(-6.0899225,4.2212071)" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect1986);" + id="text1976" + xml:space="preserve"><tspan + x="27.5" + y="3.2438663"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono'">32 32 30 0a 1f 8b 08 00 00 00 00 00 00 03 d4 ba</tspan></tspan></text> + <text + id="text1980" + y="7.4650731" + x="123.64199" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';stroke-width:0.264583" + y="7.4650731" + x="123.64199" + sodipodi:role="line" + id="tspan1978">220·············</tspan></text> + </g> + <g + transform="translate(3.8853334e-7,18.520847)" + id="g1999"> + <circle + r="0.5" + cy="17.321835" + cx="71.14006" + id="circle1993" + style="fill:#000000;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:none;paint-order:stroke fill markers" /> + <circle + style="fill:#000000;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:none;paint-order:stroke fill markers" + id="circle1995" + cx="71.14006" + cy="21.026005" + r="0.5" /> + <circle + r="0.5" + cy="24.730175" + cx="71.14006" + id="circle1997" + style="fill:#000000;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:none;paint-order:stroke fill markers" /> + </g> + <g + transform="translate(-0.0217287,40.745853)" + id="g2013"> + <text + xml:space="preserve" + id="text2003" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;line-height:1.25;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect2015)" + x="8.1588526" + y="0" + transform="translate(-0.87846032,4.2279485)"><tspan + x="0.45488887" + y="3.1389396"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';text-align:center;text-anchor:middle">0005:9980</tspan></tspan></text> + <text + xml:space="preserve" + id="text2007" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect2017);" + transform="translate(-6.0899225,4.2212071)"><tspan + x="27.5" + y="3.2438663"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono'">6e 5a a8 3d 00 36 07 00 0a </tspan></tspan></text> + <text + xml:space="preserve" + style="font-size:3.52778px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;stroke-width:0.264583" + x="123.64199" + y="7.4650731" + id="text2011"><tspan + id="tspan2009" + sodipodi:role="line" + x="123.64199" + y="7.4650731" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.52778px;font-family:'Liberation Mono';-inkscape-font-specification:'Liberation Mono';stroke-width:0.264583">nZ·=·6···</tspan></text> + </g> + </g> +</svg> diff --git a/doc/basket-archive-file-structure.png b/doc/basket-archive-file-structure.png new file mode 100644 index 0000000..2e651cf Binary files /dev/null and b/doc/basket-archive-file-structure.png differ diff --git a/doc/basket-archive-file-structure.svg b/doc/basket-archive-file-structure.svg new file mode 100644 index 0000000..8aa076e --- /dev/null +++ b/doc/basket-archive-file-structure.svg @@ -0,0 +1,208 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/"; + xmlns:cc="http://creativecommons.org/ns#"; + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"; + xmlns:svg="http://www.w3.org/2000/svg"; + xmlns="http://www.w3.org/2000/svg"; + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"; + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"; + inkscape:export-ydpi="200" + inkscape:export-xdpi="200" + inkscape:export-filename="basket-archive-file-structure.png" + sodipodi:docname="basket-archive-file-structure.svg" + inkscape:version="1.0 (4035a4fb49, 2020-05-01)" + id="svg8" + version="1.1" + viewBox="0 0 251 20.999998" + height="20.999998mm" + width="251mm"> + <defs + id="defs2"> + <rect + id="rect845" + height="19.669306" + width="26.910555" + y="0" + x="-3.5527137e-15" /> + <rect + x="-3.5527137e-15" + y="0" + width="44.609516" + height="19.475616" + id="rect859" /> + <rect + id="rect869" + height="19.475616" + width="44.609516" + y="0" + x="-3.5527137e-15" /> + <rect + id="rect883" + height="19.514832" + width="50.384212" + y="0" + x="-3.5527137e-15" /> + <rect + x="-3.5527137e-15" + y="0" + width="71.754601" + height="20.105553" + id="rect885" /> + </defs> + <sodipodi:namedview + inkscape:window-maximized="1" + inkscape:window-y="0" + inkscape:window-x="0" + inkscape:window-height="2055" + inkscape:window-width="3840" + fit-margin-bottom="0" + fit-margin-right="0" + fit-margin-left="0" + fit-margin-top="0" + inkscape:snap-bbox-midpoints="true" + inkscape:snap-bbox-edge-midpoints="true" + inkscape:bbox-nodes="true" + inkscape:bbox-paths="true" + inkscape:snap-bbox="true" + inkscape:guide-bbox="true" + showguides="true" + showgrid="false" + inkscape:document-rotation="0" + inkscape:current-layer="layer1" + inkscape:document-units="mm" + inkscape:cy="70.558354" + inkscape:cx="910.46123" + inkscape:zoom="3.959798" + inkscape:pageshadow="2" + inkscape:pageopacity="0.0" + borderopacity="1.0" + bordercolor="#666666" + pagecolor="#ffffff" + id="base"> + <sodipodi:guide + inkscape:color="rgb(0,0,255)" + inkscape:locked="false" + inkscape:label="" + id="guide849" + orientation="0,1" + position="0.49999999,10.499997" /> + </sodipodi:namedview> + <metadata + id="metadata5"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage"; /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + transform="translate(0.5,0.5)" + id="layer1" + inkscape:groupmode="layer" + inkscape:label="Layer 1"> + <rect + y="0.057285011" + x="0.057285011" + height="19.885427" + width="249.88544" + id="rect833" + style="display:inline;fill:none;stroke:#000000;stroke-width:1.11457;stroke-linecap:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;paint-order:stroke fill markers" /> + <text + transform="translate(4.1739233,1.7139271)" + y="0" + x="11.019145" + style="font-size:7.05556px;line-height:1.25;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect845)" + id="text843" + xml:space="preserve"><tspan + x="7.9188061" + y="6.4877325"><tspan + style="text-align:center;text-anchor:middle">File +</tspan></tspan><tspan + x="2.0931459" + y="15.307183"><tspan + style="text-align:center;text-anchor:middle">Header</tspan></tspan></text> + <path + id="path851" + d="M 35.739336,0 V 19.502464 H 35.516" + style="fill:none;stroke:#000000;stroke-width:0.995071;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <text + xml:space="preserve" + id="text855" + style="font-size:7.05556px;line-height:1.25;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect859)" + x="11.019145" + y="0" + transform="translate(38.440345,1.7139271)"><tspan + x="3.5685236" + y="6.4877325"><tspan + style="text-align:center;text-anchor:middle">Preview File </tspan></tspan><tspan + x="10.942755" + y="15.307183"><tspan + style="text-align:center;text-anchor:middle">Header</tspan></tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:0.995071;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M 86.332953,2.8485331e-8 V 19.502464 h -0.223336" + id="path857" /> + <text + transform="translate(82.622639,1.7139271)" + y="0" + x="11.019145" + style="font-size:7.05556px;line-height:1.25;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect869)" + id="text865" + xml:space="preserve"><tspan + x="9.9798504" + y="6.4877325"><tspan + style="text-align:center;text-anchor:middle">Preview +</tspan></tspan><tspan + x="16.768415" + y="15.307183"><tspan + style="text-align:center;text-anchor:middle">File </tspan></tspan></text> + <path + id="path867" + d="M 123.93856,5.6970181e-8 V 19.502464 h -0.22333" + style="fill:none;stroke:#000000;stroke-width:0.995071;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <text + transform="translate(130.11152,1.7139271)" + y="0" + x="11.019145" + style="font-size:7.05556px;line-height:1.25;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect883)" + id="text873" + xml:space="preserve"><tspan + x="0.26537833" + y="6.4877325"><tspan + style="text-align:center;text-anchor:middle">Content Archive </tspan></tspan><tspan + x="13.830451" + y="15.307183"><tspan + style="text-align:center;text-anchor:middle">Header</tspan></tspan></text> + <path + id="path875" + d="M 187.08266,5.6970181e-8 V 19.502464 h -0.22334" + style="fill:none;stroke:#000000;stroke-width:0.995071;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <text + xml:space="preserve" + id="text879" + style="font-size:7.05556px;line-height:1.25;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect885)" + x="11.019145" + y="0" + transform="translate(182.57106,1.7139271)"><tspan + x="10.949949" + y="6.4877325"><tspan + style="text-align:center;text-anchor:middle">Content Archive +</tspan></tspan><tspan + x="30.340681" + y="15.307183"><tspan + style="text-align:center;text-anchor:middle">File </tspan></tspan></text> + <path + style="display:none;fill:none;stroke:#000000;stroke-width:0.995071;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 249.96839,0 v 19.502464 h -0.22333" + id="path881" /> + <path + style="display:none;fill:none;stroke:#000000;stroke-width:0.995071;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M -0.0024645,1.0045745e-6 V 19.502465 h -0.223336" + id="path887" /> + </g> +</svg> diff --git a/doc/index.docbook b/doc/index.docbook index 3055e67..9554516 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -1,123 +1,206 @@ <?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ - <!ENTITY basket "<application>BasKet</application>"> +<!ENTITY basket "<application>BasKet</application>"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE" > <!-- change language only here --> ]> <book id='basket' lang="&language;"> - <bookinfo> - <title>The &basket; Handbook</title> - <authorgroup> - <author> - <personname> - <firstname>Gleb</firstname> - <surname>Baryshev</surname> - </personname> - <email>[email protected]</email> - </author> - </authorgroup> - <date>2016-11-07</date> - <releaseinfo>2.11</releaseinfo> - - <abstract> - <para>Taking care of your ideas.</para> - </abstract> - <keywordset> - <keyword>KDE</keyword> - <keyword>BasKet</keyword> - <!--keyword>note pad</keyword--> - </keywordset> - </bookinfo> - - <chapter id="notice"> - <title>NOTICE: handbook not written yet</title> - <para>&basket; still does not have a handbook, so contributors are welcome! - Check the <ulink url='https://l10n.kde.org/docs/doc-primer/index.html'> - KDE documentation</ulink> for the hints on the DocBook format.</para> - <para>Meanwhile, you can look for help on the Internet. In particular, - look through the <ulink url='https://basket-notepads.github.io'>old website</ulink> or - check Linux magazines if you have access to them, for example: - <itemizedlist> - <listitem><para> - <quote>Tutorial: Basket: Capture your thoughts.</quote> Linux Format 120 - (Andy Channelle) - </para></listitem> - <listitem><para> - <quote>A Virtual Basket. Storing, sorting, and filing with KDE's - Basket</quote> Linux Magazine 54 (Stefanie Teufel) - </para></listitem> - </itemizedlist> - </para> - </chapter> - - <chapter id="introduction"> - <title>Introduction</title> - <para>&basket; is mainly an all-purpose notes taker, but a particular one:</para> - </chapter> - - <chapter id="using-BasKet"> - <title>Using BasKet</title> - <para></para> - <sect1> - <title>Version Sync</title> - <para>When enabled, Version Sync puts your baskets and notes under version control. Currently this is an experimental feature and only very basic functions are implemented, so it may require additional software and some manual setup. These are some of the things that can be done using external tools (but not Basket interface yet):</para> - <itemizedlist> - <listitem> - <para>check out old revisions and revert the changes</para> - </listitem> - <listitem> - <para>synchronize baskets on several computers (merge the changes)</para> - </listitem> - <listitem> - <para>push baskets backup to remote repository</para> - </listitem> - </itemizedlist> - <para>To enable it, select - <menuchoice> - <guimenu>Settings</guimenu> <guimenuitem>Configure BasKet Note Pads</guimenuitem> - </menuchoice> - → <guibutton>Version Sync</guibutton> - and <guibutton>Enable distributed version control</guibutton>. It will initialize git repository in <filename>~/.kde/share/apps/basket/baskets</filename>, upon which standard git tools can be used.</para> - <sect2> - <title>Clearing version history</title> - <para>Clearing the history can be useful in these cases:</para> - <itemizedlist> - <listitem> - <para>you have locked a basket and want to remove any previous unencrypted versions (which are still stored in the system)</para> - </listitem> - <listitem> - <para>you want to free some disk space (can be topical if you insert a lot of images or other files into Basket)</para> - </listitem> - </itemizedlist> - <para>Note that you will have to redo any manual setup you did on the git repository.</para> - </sect2> - </sect1> - </chapter> - - <chapter id="questions-answers-and-tips"> - <title>Questions, Answers, and Tips</title> - - <qandaset id="faq"> - <title>Frequently asked questions</title> - <qandaentry> - <question> - <para>Question 1</para> - </question> - <answer> - <para>The answer</para> - </answer> - </qandaentry> - </qandaset> - - </chapter> -</book> -<!-- -Local Variables: -mode: sgml -sgml-omittag: nil -sgml-shorttag: t -sgml-general-insert-case: lower -End: ---> + <bookinfo> + <title>The &basket; Handbook</title> + <authorgroup> + <author> + <personname> + <firstname>Gleb</firstname> + <surname>Baryshev</surname> + </personname> + <email>[email protected]</email> + </author> + </authorgroup> + <date>2016-11-07</date> + <releaseinfo>2.11</releaseinfo> + + <abstract> + <para>Taking care of your ideas.</para> + </abstract> + <keywordset> + <keyword>KDE</keyword> + <keyword>BasKet</keyword> + <!--keyword>note pad</keyword--> + </keywordset> + </bookinfo> + + <chapter id="notice"> + <title>NOTICE: handbook not written yet</title> + <para>&basket; still does not have a handbook, so contributors are welcome! + Check the <ulink url='https://l10n.kde.org/docs/doc-primer/index.html'> + KDE documentation</ulink> for the hints on the DocBook format.</para> + <para>Meanwhile, you can look for help on the Internet. In particular, + look through the <ulink url='https://basket-notepads.github.io'>old website</ulink> or + check Linux magazines if you have access to them, for example: + <itemizedlist> + <listitem><para> + <quote>Tutorial: Basket: Capture your thoughts.</quote> Linux Format 120 + (Andy Channelle) + </para></listitem> + <listitem><para> + <quote>A Virtual Basket. Storing, sorting, and filing with KDE's + Basket</quote> Linux Magazine 54 (Stefanie Teufel) + </para></listitem> + </itemizedlist> + </para> + </chapter> + + <chapter id="introduction"> + <title>Introduction</title> + <para>&basket; is mainly an all-purpose notes taker, but a particular one:</para> + </chapter> + + <chapter id="using-BasKet"> + <title>Using BasKet</title> + <para></para> + <sect1> + <title>Version Sync</title> + <para>When enabled, Version Sync puts your baskets and notes under version control. Currently this is an experimental feature and only very basic functions are implemented, so it may require additional software and some manual setup. These are some of the things that can be done using external tools (but not Basket interface yet):</para> + <itemizedlist> + <listitem> + <para>check out old revisions and revert the changes</para> + </listitem> + <listitem> + <para>synchronize baskets on several computers (merge the changes)</para> + </listitem> + <listitem> + <para>push baskets backup to remote repository</para> + </listitem> + </itemizedlist> + <para>To enable it, select + <menuchoice> + <guimenu>Settings</guimenu> <guimenuitem>Configure BasKet Note Pads</guimenuitem> + </menuchoice> + → <guibutton>Version Sync</guibutton> + and <guibutton>Enable distributed version control</guibutton>. It will initialize git repository in <filename>~/.kde/share/apps/basket/baskets</filename>, upon which standard git tools can be used.</para> + <sect2> + <title>Clearing version history</title> + <para>Clearing the history can be useful in these cases:</para> + <itemizedlist> + <listitem> + <para>you have locked a basket and want to remove any previous unencrypted versions (which are still stored in the system)</para> + </listitem> + <listitem> + <para>you want to free some disk space (can be topical if you insert a lot of images or other files into Basket)</para> + </listitem> + </itemizedlist> + <para>Note that you will have to redo any manual setup you did on the git repository.</para> + </sect2> + </sect1> + </chapter> + + <chapter id="basket-file-structure"> + <title>BasKet file structure</title> + + <sect1 id="basket-file-structure-intro"> + <title>Introduction</title> + <para></para> + </sect1> + + <sect1 id="basket-archive-file-format"> + <title>BasKet Archive file format</title> + <para>The BasKet file format (.baskets) is a structure which wraps a compressed tar and a preview image. The latest archive format version is 0.6.1.</para> + + <sect2 id="basket-archive-file-structure"> + <title>File Structure</title> + <para>The archive file is devided into the structures: file header, preview image header, a preview image (.png), archive header, and a gunzipped tar archive (.tar.gz) containing a baskets file tree as illustrated in the following sketch</para> + <mediaobject id="basket-archive-file-structure-graph"> + <imageobject> + <imagedata format="PNG" fileref="basket-archive-file-structure.png"/> </imageobject> + </mediaobject> + </sect2> + + <sect2 id="archive-file-header"> + <title>Archive file header</title> + <para>The file header is a short structure, consisting of lines of strings, the file declarator, and the format version</para> + + <para>The first 17 bytes contain the literal string <code>BasKetNP:archive</code> followed by a new line feed symbol (0x0A) in ISO-8859-1 encoding.</para> + <para>The second string is a literal string <code>version:0.6.1</code> followed by a line feed symbol (0x0A) in ISO-8859-1 encoding.</para> + <para>An example:</para> + <programlisting> + <![CDATA[ +BasKetNP:archive +version:0.6.1 + ]]> + </programlisting> + </sect2> + + <sect2 id="archive-file-preview-header"> + <title>Preview image header</title> + <para>Currently, the basket archive file contains a preview file which is derived from the first basket's content.</para> + <para>Directly following the file header, a literal string <code>preview*:<size></code> in ISO-8859-1 encoding, again followed by a line feed symbol. The parameter <code><size></code> is a string of decimal numbers. It declares the size in bytes of the preview image. <code><size></code> is of type unsigned long.</para> + <para>An example:</para> + <programlisting> + <![CDATA[ +preview*:12000 + ]]> + </programlisting> + </sect2> + + <sect2 id="archive-file-preview"> + <title>Preview image file</title> + <para>The preview image is of type .png. Its size is specified by the preview image header. The preview image file is inserted as file stream, and directly follows the preview image header.</para> + </sect2> + + <sect2 id="content-archive-file-header"> + <title>BasKet content archive header</title> + <para>Just like for the previe image file, the content archive is preceded by a string specifying its size. That string directly follows the file stream of the preview image.</para> + <para>That string must be <code>archive*:<size></code> followed by a line feed symbol, in ISO-8869-1 encoding. The parameter <code><size></code> is a unsigned long integer in string format.</para> + <para>An example:</para> + <programlisting> + <![CDATA[ +archive*:1245000 + ]]> + </programlisting> + </sect2> + + <sect2 id="content-archive-file"> + <title>BasKet content archive</title> + <para> The content archive contains the BasKet file tree compressed in to a gzipped tar archive (.tar.gz). Its size is size is specified by the content header.</para> + </sect2> + + <sect2 id="basket-archive-file-content-example"> + <title>Example byte stream</title> + <para>The following table shows key parts of the basket archive file content. The left column specifies the offset in the file stream. The center column gives the byte stream at the current offset in hexadecimal format. The right column shows printable characters within the file stream at the current offset.</para> + <mediaobject id="file-content-example"> + <imageobject> + <imagedata format="PNG" fileref="basket-archive-file-content-example.png"/> </imageobject> + </mediaobject> + </sect2> + + </sect1><!--archive file format--> + + </chapter><!--basket file structure--> + + <chapter id="questions-answers-and-tips"> + <title>Questions, Answers, and Tips</title> + + <qandaset id="faq"> + <title>Frequently asked questions</title> + <qandaentry> + <question> + <para>Question 1</para> + </question> + <answer> + <para>The answer</para> + </answer> + </qandaentry> + </qandaset> + + </chapter> + </book> + <!-- + Local Variables: + mode: sgml + sgml-omittag: nil + sgml-shorttag: t + sgml-general-insert-case: lower + End: + -->
