Changeset 23 in projects for schriften/font_files.htm


Ignore:
Timestamp:
Dec 22, 2008, 3:47:40 AM (11 years ago)
Author:
sven
Message:

Documentation:

  • documentation/index.php: New small wrapper system that puts any HTM file in this reposity in a small homepage
  • README.txt => README.htm conversion in most of the subprojects

-- Sven @ workstation

File:
1 moved

Legend:

Unmodified
Added
Removed
  • schriften/font_files.htm

    r18 r23  
    1 
    2   The Paper Tape Project -- Paper Tape Font files
    3   ===============================================
    4 
    5 I have developed a portable and easy to use ASCII storage format
    6 for paper tape fonts. While paper tape fonts were formerly
    7 implemented as (perl) scripts, with C (and C++) that's no more
    8 practical, because setting up big nested hashes is not really
    9 possible. Apart from that, it would not be a good style to set
    10 up a giant header file with so much static data.
    11 
    12 I have considered using popular and approved data formats like
    13 XML or Jason instead of a "proprietary" new, perhaps even binary
    14 data format. On the one hand, using XML would have been really
    15 portable, but also very unhandy, because I would have to look
    16 for XML processors for Windows, and compiling would be get
    17 complex and even more complex.
    18 
    19 Therefore I've decided in favor of simple ASCII files with some
    20 not very strict layout. It's really obvious how it works:
    21 
     1<html>
     2<body>
     3
     4<h2>Paper Tape Font files</h2>
     5<p>I have developed a portable and easy to use ASCII storage format
     6   for paper tape fonts, called <b>Paper Tape Font file</b>. While
     7   paper tape fonts were formerly implemented as (perl) scripts,
     8   with C (and C++) that's no more
     9   practical, because setting up big nested hashes is not really
     10   possible. Apart from that, it would not be a good style to set
     11   up a giant header file with so much static data.</p>
     12
     13<p>I have considered using popular and approved data formats like
     14   <i>XML</i> or <i>Jason</i> instead of a "proprietary" new, perhaps
     15   even binary data format. On the one hand, using XML would have been
     16   really portable, but also very unhandy, because I would have to look
     17   for XML processors for Windows, and compiling would be get
     18   complex and even more complex.</p>
     19
     20<p>Therefore I've decided in favor of simple ASCII files with some
     21   not very strict layout. It's really obvious how it works:</p>
     22
     23<pre>
    2224|***.***  |a   You can write texts almost everywhere in the file,
    2325|   .*  * |a   just the very first letters, which actually
     
    2830|*  .*   *|e   Yes, that's it! This file is a complete papertape
    2931|*  .    *|e   font file, containing (until now) the letters a and e.
    30 
    31 
    32   Specification of Paper Tape files
    33   =================================
    34 
    35 This is a typical paper tape file:
    36 
     32</pre>
     33<!-- yeay, this HTML file is a paper tape file! -->
     34
     35<h3>Specification of Paper Tape files</h3>
     36
     37<p>This is a typical paper tape file:</p>
     38<pre>
    3739---- Start of example file ----
    3840The Paper Tape Project -- PAPERTAPE_FONT file.
     
    6769
    6870----  End of example file  ----
    69 
    70 As you see, paper tape files are quite funny ASCII files. Here are the
    71 rules you have to observe:
    72 
    73  * All lines are ignored, if there's not a papertape border in the
    74    very first position. The papertape border is defined as
    75    the pipe character, "|".
    76 
    77  * The papertape "flows" from top to down, like western european
    78    people write. The bit positions are also from left to right, like
    79    a real paper tape looks like, including the feed hole between
    80    bit 3 and 4. Therefore, as the key says, you read a paper tape byte
    81    like that:
    82 
    83         |123.45678| <- bit positions
    84         |012.34567| <- how computers count the bits
    85    e.g. | * . ** *| -> byte value = 2^1 + 2^4 + 2^5 + 2^7 = 178 = 0xbd
    86 
    87  * It's up to you which character you use for indicating an hole
    88    (logical 1). The only limitation is, that a logical 0 (not holed)
    89    MUST be an white space (no tab! Only the whitespace character).
    90    So all these bytes have the equal values:
     71</pre>
     72
     73<p>As you see, paper tape files are quite funny ASCII files. Here are the
     74rules you have to observe:</p>
     75
     76<ul>
     77<li>All lines are ignored, if there's not a papertape border in the
     78    very first position. The papertape border is defined as
     79    the pipe character, "<tt>|</tt>".</li>
     80
     81<li>The papertape "flows" from top to down, like western european
     82    people write. The bit positions are also from left to right, like
     83    a real paper tape looks like, including the feed hole between
     84    bit 3 and 4. Therefore, as the key says, you read a paper tape byte
     85    like that:
     86<pre>
     87        |123.45678| &lt;- bit positions
     88        |012.34567| &lt;- how computers count the bits
     89   e.g. | * . ** *| -&gt; byte value = 2^1 + 2^4 + 2^5 + 2^7 = 178 = 0xbd
     90</pre>
     91</li>
     92
     93<li>It's up to you which character you use for indicating an hole
     94    (logical 1). The only limitation is, that a logical 0 (not holed)
     95    MUST be an white space (no tab! Only the whitespace character).
     96    <br/>So all these bytes have the equal values:
     97<pre>
    9198        |+ +.++ ++|
    9299        |h e.ll oo|
     
    95102        |( ).() ()| (also not recommendable)
    96103        |* *.** **|
    97 
    98  * To allocate a byte to a character, you write that character directly
    99    after the papertape,
     104</pre></li>
     105
     106<li>To allocate a byte to a character, you write that character directly
     107    after the papertape,
     108<pre>
    100109     like this:         | * . ** *|r
    101110     but not like this: |  *.* ***| w
    102    That character is called the "ASCII identifier", because it shall be
    103    ASCII (8bit). You can write comments right after the identifier,
    104    because everything afterwards will be ignored.
    105 
    106  * There are three cases of bytes:
     111</pre>
     112    That character is called the "ASCII identifier", because it shall be
     113    ASCII (8bit). You can write comments right after the identifier,
     114    because everything afterwards will be ignored.
     115</li>
     116
     117<li>There are three cases of bytes:
     118<pre>
    107119    * the normal byte        |***.*****|p
    108120      that belongs to an     |   .*   *|p
     
    113125    * bytes that belong to   |** . ****| special_character
    114126      special characters.    |  *.*    | special_character
     127</pre>
    115128   We give attention to special characters later.
    116 
    117  * Typically your paper tape letters span across multiple bytes. In
    118    Paper Tape files, you write next to *every* byte the character where
    119    it belongs to. This is read afterwards from up to down, like the
    120    virtual paper tape direction is:
     129</li>
     130
     131<li>Typically your paper tape letters span across multiple bytes. In
     132    Paper Tape files, you write next to <u>*every*</u> byte the character where
     133    it belongs to. This is read afterwards from up to down, like the
     134    virtual paper tape direction is:
     135<pre>
    121136       |***.*****|p
    122137       |   .*   *|p
    123138       |   . *** |p
    124        |   .     |   <- this line doesn't belong to p any more.
     139       |   .     |   &lt;- this line doesn't belong to p any more.
     140</pre>
    125141   Don't mix up with letters. Compare these examples:
     142<pre>
    126143       |***.*****|p                  |***.*****|p
    127144       |   .*   *|p                  |   .*   *|p
     
    133150       |   .   * |y                  |   .   * |y
    134151       |   .    *|y                  |   .    *|y
     152</pre>
    135153   The typo at the right ("p" instead of "y") will overwrite the
    136154   defined paper tape letter "p" above, because letters will always
     
    138156   too, by the later 3 "y" lines. That is, due to the typo error, all
    139157   previous definitions of "p" and "y" before are thrown away.
    140    Compare also these examples:
     158   <br/>Compare also these examples:
     159<pre>
    141160       |***.*****|p                  |***.*****|p
    142161       |   .*   *|p                  |   .*   *|p
     
    144163       |   . *** |p                  |   . *** |p
    145164       |   .     |                   |   .     |
     165</pre>
    146166   While the comment line on the left hand example is simply ignored,
    147167   the white space byte on the right hand side is parsed and therefore
    148168   the "p" value destroyed, like in the "y" and "p" example above.
    149 
    150  * Next to the normal ASCII characters, there are special characters.
    151    Principally, they are treated like ordinary characters, but they
    152    are not identified with an ASCII value, but with a full name:
     169</li>
     170
     171<li>Next to the normal ASCII characters, there are special characters.
     172    Principally, they are treated like ordinary characters, but they
     173    are not identified with an ASCII value, but with a full name:
     174<pre>
    153175       |***.*****|p
    154176       |   .*   *|p  This is an ordinary ASCII character
     
    176198       |** . *** | =secret_file    byte definitions: Don't break in
    177199       |*  .  *  | =secret_file    the flow, like
    178        |   .     |                 <- here, because this would
    179        | * .*    | =secret_file    truncate secret_file to <-this byte.
    180 
    181  * Take care that the papertapefont implementation can also write
    182    paper tape font files. If the utility program is called to change
    183    one character in your font file, it will read in (and parse) the
    184    font file and write back the parsed files (including the changes,
    185    of course). In this process, *ALL* your comments are *LOST*.
    186    The implementation cannot take care of your comments, this would
    187    be too complex.
    188    So if your font file is well commented, don't let the implementation
    189    write to it.
    190 
    191 
    192 
    193   Specification of the papertapefont.h library
    194   ============================================
    195 
    196   I've developed a tiny stand alone C library which does not need
    197   auxillary libraries like Glib and which will compile at windows,
    198   too. It's quite simple to use that library. At first, there even
    199   exists a command line interface that implements most of the
    200   features. But here's how to use the C functions:
    201 
    202   The main "object like" structure is the PAPERTAPE_FONT structure.
    203   It can be built directly by parsing an already opened file:
    204 
    205     #include <stdio.h>
     200       |   .     |                 &lt;- here, because this would
     201       | * .*    | =secret_file    truncate secret_file to &lt;-this byte.
     202</pre>
     203</li>
     204
     205<li>Take care that the papertapefont implementation can also write
     206    paper tape font files. If the utility program is called to change
     207    one character in your font file, it will read in (and parse) the
     208    font file and write back the parsed files (including the changes,
     209    of course). In this process, *ALL* your comments are *LOST*.
     210    The implementation cannot take care of your comments, this would
     211    be too complex.
     212    <br/>
     213    So if your font file is well commented, don't let the implementation
     214    write to it.</li>
     215
     216</ul>
     217
     218<h3>Specification of the papertapefont.h library</h3>
     219<p>I've developed a tiny stand alone C library which does not need
     220   auxillary libraries like Glib and which will compile at windows,
     221   too. It's quite simple to use that library. At first, there even
     222   exists a command line interface that implements most of the
     223   features. But here's how to use the C functions:</p>
     224
     225<p>The main "object like" structure is the PAPERTAPE_FONT structure.
     226   It can be built directly by parsing an already opened file:</p>
     227<pre>
     228    #include &lt;stdio.h&gt;
    206229    #include "papertapefont.h"
    207230
    208231    FILE* font_file = fopen("/path/to/your/font.file", "r");
    209232    PAPERTAPE_FONT* font = papertape_font_new_from_file(font_file);
    210 
    211   Now the file has been parsed and every available letter is stored
    212   in RAM. So you can directly go and generate labels:
    213 
     233</pre>
     234
     235<p>Now the file has been parsed and every available letter is stored
     236   in RAM. So you can directly go and generate labels:
     237
     238<pre>
    214239    int label_size;
    215240    byte_t* label_bytes;
     
    221246    LOCHSTREIFEN* papertape = lochstreifen_new();
    222247    lochstreifen_set_data(label_bytes, label_size);
    223 
    224   Of course you can check if your string can be fully generated, too:
    225 
     248</pre>
     249
     250<p>Of course you can check if your string can be fully generated, too:
     251
     252<pre>
    226253    if(! papertape_font_string_is_printable(font, "{H4x05]!")) {
    227254        printf("Sorry dude, the current font is not"
    228255               "script kiddie compatible.\n");
    229256    }
    230 
    231   And after all, changing the papertape is fully implemented:
    232 
     257</pre>
     258
     259<p>And after all, changing the papertape is fully implemented:</p>
     260
     261<pre>
    233262    bytes_t* user_generated;
    234263    int len;
    235264
    236265    let_user_generate_letter("Please make an 'A'",
    237       &user_generated, &len);
     266      &amp;user_generated, &amp;len);
    238267
    239268    papertape_font_set_char(font, 'A', user_generated, len);
    240 
    241   This will change the letter immediately. So the following output
    242   will give out "ABBA" on the papertape at the end (and not "ABAB"):
    243 
     269</pre>
     270
     271<p>This will change the letter immediately. So the following output
     272   will give out "ABBA" on the papertape at the end (and not "ABAB"):
     273
     274<pre>
    244275    bytes_t* output, buf_for_a, buf_for_b;
    245276    int      o_len,  a_len,     b_len;
     
    258289    output = papertape_font_get_label(font, "ab", &o_len);
    259290    send_to_papertape_puncher(output, o_len);
    260 
    261   If you feel destructive, you can also delete characters:
    262 
     291</pre>
     292
     293<p>If you feel destructive, you can also delete characters:
     294
     295<pre>
    263296    // clean up all the mess by deleting everything!!111
    264297    papertape_font_del_char(font, 'a');
     
    269302    // this will give out 4 errors at stderr, because
    270303    // no character can be generated.
    271 
    272   At last, after messing around you can save the whole changed
    273   thing (back) to a file.
    274 
     304</pre>
     305
     306<p>At last, after messing around you can save the whole changed
     307   thing (back) to a file.
     308
     309<pre>
    275310    FILE* target = fopen("/existing/or/new.font.txt", "w");
    276311    papertape_font_write_to_file(font, target);
    277 
    278   Be aware that the following example will stripe out *ALL*
    279   comments out of your font file:
    280 
     312</pre>
     313
     314<p>Be aware that the following example will stripe out *ALL*
     315   comments out of your font file:
     316
     317<pre>
    281318    FILE* needs_cleanup = fopen("font.txt", "r+");
    282319    PAPERTAPE_FONT* font = papertape_font_new_from_file(needs_cleanup);
    283320    papertape_font_write_to_file(font, needs_cleanup);
    284 
    285   In the end, an issue that is a bit more complicated: Special
    286   characters. This includes white spaces, letter spacing, etc.
    287   The names for these special characters are noted in the
    288   papertapefont.h header file, so you can access them directly,
    289   too, if you want:
    290 
     321</pre>
     322
     323<p>In the end, an issue that is a bit more complicated: Special
     324   characters. This includes white spaces, letter spacing, etc.
     325   The names for these special characters are noted in the
     326   papertapefont.h header file, so you can access them directly,
     327   too, if you want:
     328
     329<pre>
    291330    byte_t *white = calloc(sizeof(byte_t), 100);
    292331    papertape_font_set_special(font, PAPERTAPE_FONT_SPACE_NAME,
     
    298337    // so this is quite short:
    299338    papertape_font_get_label(font, "  s h o r t  ", &somewhere);
    300 
    301   I think that's all, for the moment. Happy coding :-)
    302 
    303 
    304   -- Sven Köppel, 04.09.2008
     339</pre>
     340
     341<p>I think that's all, for the moment. Happy coding :-)
     342
     343<p>-- Sven Köppel, 04.09.2008
Note: See TracChangeset for help on using the changeset viewer.
© 2008 - 2013 technikum29 • Sven Köppel • Some rights reserved
Powered by Trac
Expect where otherwise noted, content on this site is licensed under a Creative Commons 3.0 License