Manufacturing DOC how-to ------------------------ NJako reakci na pozadaev vyrabet vnikl malej system pro vyrobni dokumentaci, kteryzto se v CBS nachazi pod modulem Manufacturing, v documentation casti. Jak funguje ----------- System funguje na bazi SVN, se kterym je silne provazan. Sam o sobe nemoznuje delat zadne zasahy do dat, nebo je menit. Ze SVN se tahaji 2 typy souboru: datove a textove. Ty prvni se nikterak nezpracovavaji a ty druhe ano. Par pravidel ------------ - jmeno souboru by nemelo obsahovat mezeru a podobne nesmyslne znaky -> muze (a nemusi) zpusobit nekde problem - lodovani textovych souboru musi byt vzdy a pouze UTF-8 (bez vyjimky). - jmena souboru mohou obsahovat jen ANSI znaky (zadne hacky carky a podobne nesmysly) - jmena revizi nesmi obsahovat mezeru - pokud je nekde uveden 'alias' - jedna se o text z ANSI znaku bez mezer (zadne hacky carky) - referencuje 'enter' - jako znak noveho radku (a podobne) - pozor na mezery - nekdy je mezera navic problem, napriklad '2' praznde radky musi byt opravdu prazdne tj. bez mezer. Dtto napr. odstavec tvoreny : a nasledne . V pripade vizualni chyby zkontrolovat zda-li se nevloudila mezera kam nema - nelze pouzivat jakekoliv HTML elementy - sloupec v chybovych hlaskach muze byt nepresny (vzhledem ke zpracovani) - jesli jsou na radku pouzity znaky, ktere se v HTML musi entitiovat (to jest: < > & ' ") tak sloupec bude o neco mensi, nez ma byt tj. v tomto pripade je chyba nekde dal napravo od reportovaneho sloupce - znak [ je vyhrazen pro direktivy. Pokud za znakem nasleduje pismeno, nastava kolize a direktivou. Pokud je potreba napsat znak [ s pismenem ihned za, je nutno v tomto pripade pouzit [[ a to se prevede na [ Stejne tak plati: [[[ -> [[ a [[[[ -> [[[ a [[[[[ -> [[[[ priklad: [[prdlajz] se prelozi jako '[prdlajz]' a nezobrazi se chyba 'neznama direktiva' [[include neco.txt] se prelozi jako '[include neco.txt]' a soubor neco.txt se includovat nebude Odkazy na soubory ----------------- Obecny format odkazu na soubor je: [knihovna:][/][cesta/k/souboru/]soubor Priklady: soubor.pdf shared:soubo.jpg pcb:/nazev-desky/bom.zip pcb:nazev-desky/bom.zip Je dovoleno pouzivat \ misto / (oba zapisy funguji identicky). Uvozujici / je volitelne. Knihovny -------- Aby bylo mozne pouzivat a odkazovat soubory mimo 'dokumentaci' existuji knihovny. Ty se definuji online. Kazda knihovna ma zaklad nekde v SVN (cesta) a jmeno. Pomoci jmena se pak prefixuje v prikazu pro referenci obsahu. folder_no_revs -------------- tento druh knihovny vezme obsah adresare, kazdy adresar vezme jako knihovnu a soubory v ni bez vazby na revize pak umoznuje referencovat. Typicky se jedna o PCB data. Priklad: definuju knihovnu 'pcb' a tu ukazu na Manufacturing SVN na adresar 'pcb_boards'. V teto sturkture pak muzu odkazat na tento soubor. Jmeno adresare normalne vystupuje jako adresar v ceste. files_with_revs --------------- Soubory ylozene v dane ceste, ktere se verzuji - v okamziku release je 'zapamatovan' jejich aktualni stav (revize). Dalsi zmeny v souboru jsou povolene, nicmene veskere release zustavaji tak jak jsou (retrospektivni aktivita je tedy nemozna). Adresare pritomne v dane SVN ceste jsou ignorovany. files_in_dirs_with_revs ----------------------- Funguje obdobne jako files_with_revs s tim rozdilem, ze je nactena kompletni adresarova struktura. Soubory z knihoven se pouzivaji jako jakekoli jine - jen s prefixem. Kontext ------- System si pamatuje aktualni 'stack' v ramci ruznych includu (knihovny napriklad), takze jako prvni se zkousni 'nejvnitrnejsi' (aktualni) kontext. Proto je mozne odkazat na 1 soubor ruznou cestou. Napriklad: mejme soubor 'neco.txt' v knihovne 'shared'. Pokud tento soubor odkazuji z nejakeho produktu potom je jeho cesta: shared:neco.txt. Nicmene, pokud mame v shared 'spolecne.txt' ktery tento soubor odkazuje taktez, potom spolecne.txt obsahuje pouze 'neco.txt'. Pokud by dokumentace mela soubor 'neco.txt' stejne jako shared, potom reference na 'neco.txt' v obou pripadech skonci u JINEHO (ale spravneho) souboru ! Pokud 'knihovna' odkazuje na soubor, ktery neni v dane knihovne umistnen, system se ho pokusi (nakonec) najit i v ramci dane dokumentace. To znamena, ze pokud by soubor ze shared odkazoval na 'blabla.txt' a prislusna dokumentace ho obsahovala, tak se na nej vytvori spravna reference. Toto chovani je mozne zneuzit k tomu, kdy prislusny text je identicky, ale napr. obrazek je ruzny. Potom tento ruzny obrazek musi byt soucasti dokumentace nicmene kazda ho bude mit 'svuj'. Documentace ----------- Dokumentace je tvorena adresari, kde kazdy adresar reprezentuje jednu revizi. V tomto adresari jsou pak soubory. Zde nejsou podporovany zadne dalsi adresare (muzeme pridat pro prehlednost). Tj. kazde jmeno souboru je unikatni. V dobe buildy system varie nad ignorovanyma adresarema. Dokumentace zacina souborem 'index.txt'. Tento soubor system zpracuje. Direktivy nahradi vysledkem jejich zpracovani. Vse ostatni pak preda na vystup. Vystupem dokumentace je jeden HTML soubour spolu s radou 'priloh' (stahuje se jako ZIP). Soucasti tohto souboru je: 1. obsah 2. text 3. seznam chyb 4. seznam pouzitych souboru a jejich hash Direktivy --------- Direktiva je cast textu, uzavrena mezi hranate zavorky [obsah]. Direktivu system zpracovava a nahradi ji jejim vystupem. Vystup direktivy muze byt vlozeny soubor, odkaz, ... cokoliv. Obecne direktivy, ktere maji vice parametru umozni pouzit znak | k jejich oddeleni. Nektere parametry jsou nepovine. [include jmeno_souboru] ----------------------- Tato direktiva vezme uvedeny soubor a zpracuje ho tak, jako kdyby byl na miste direktivy soubour sam o sobe. [file jmeno_souboru | jmeno odkazu] -------------------- Umisti odkaz na soubor. Pokud neni dano 'jmeno odkazu' pojmenuje odkaz proste jmenem souboru. [x. nadpis | odkaz] [x.x. nadpis | odkaz] [x.x.x. nadpis | odkaz] ----------------------- Definice nadpisu prvni, druhe nebo treti urovne. Odkaz je alias. Pokud je uveden, je tak odkaz pojmenovat. Pokud ne, vygeneruje system (je nutno pro klikani). Aktualne mam implementovanou prvni uroven, protoze se jina nepouziva, ale zdrojaky pocitaji se 3ma. [ref cil] --------- Odkaz na 'cil'. Cil je alias, ktery se nachazi v ramci textu, typicky definovan pomoci nadpisu. Tj. pokud chci odkazat na nejakou konkretni cast, musim ji definovat alias. System nahradi alias kompletne celym nadpisem, vcetne cisla (neho ho treba muze zkratit, ... to vsechno je mozne si urcit). [table nadpis|typ] ----------------- nasleduje 'seznam', kazdy radek seznamu musi zacinat '- ' (pomlcka mezera) na zacatkur radku. Pomlcka ukoncuje seznam. Pokud neni typ zadan, jedna se o neocislovany seznam. '123' pak znamena klasicky cislovany seznam. Nadpis taktez nemusi byt zadan. Nadpis, ktery koliduje s typem (tj. 123 napr.) nelze pouzit. [table volba|volba2|volba3=hodnota|...] --------------------------------------- tabulka :) Bunky se oddeluji pomoci | (pipe, cesky svislitko). Konec radku je konec radku v tabulce. Tabulka konci 2x prazdnym radkem. Prazne znaky na zacatku a konci bundky jsou odstraneny. Lze tedy | pouzivat i jako vizualni formatovac. Priklad: [table] prvni|druha|soucet 1 | 2 | 3 3 | 8 | 11 volby jsou volitelne. Nektere z nich maji hodnotu. Ty jsou aktualne tyto: header prvni radek bude v tabulce 'zvyraznen' Komentare --------- Komentar je cast textu, ktera se nepredava na vystup, neucastni se kontrolnich souctu a jeho zmena nema ani za nasledek zmenu celkoveho HASHe. Existuji 2 komentare: jednoradkovy ------------ ma format jako direktiva: [- komentar] viceradkovy ----------- Stejny ako jkednoradkovy, ale zde jsou minimalne 3 pomlcky. Komentar se ukoncuje stejnym zpusobem jako zacatek. Komentare muzou byt vnorene. Fyzicky se ignoruej vsechno, vcetne koncu radku a podobne. Priklad: [--- viceradkovy komentar a jeho konec ---] Pokud je nekde sekce s komentarem, ktera se ma taktez zakomentovat, potom staci pouzit [---- na vnejsku a tim padem nebudou kolidovat vnitrni komentare. Retezeni (to jest pocitani koncu a zacatku) neni mozne - to co je uvnitr komentare se ignoruje. Misto zretezeni (ktere je bezne jen zakazane) je mozne pouzit vice pomolcek, tedy vide adidas. Formatovani ----------- Text se prenasi 'tak jak je' kromne nize popsanych pripadu. Protoze se zobrazuje jako text, 'konec' radku (enter) nic nedela :) odstavec s lokalnim nadpisem: nadpis:telo odstavce ----------------------------- Jeslize se tato kontrukce pouzije, tak se vygeneruje 'nadpis' a 'telo' bude osazeno o jednu uroven doprava. Pozor na mezery za : ! novy radek musi nasledovat bezprostredne za : Tucne pismo ----------- Zvyraznit jde pomoci *text* kde pred prvni a za druhou * musi byt 'prazdno' (zacatek/konec radku, mezera). V tom pripade jsou * odebrany a vnitrek zobrazen tucne. Nadpis: Jeden radek s nadpisem ------- Udela nadpis. Bez zasahu do cislovani kapitol. Odstavec: -------- 5x (nebo vice) entru zalomi odstavec Ovladani -------- Web se ovlada snadno, takze jen par pozmanek: 'SVN sync' provadi synchronizaci na urovni SVN, muze chvilku trvat. Revize 'next' je jedina, ktera ma funknci 'udpate' - rychle nacteni zmen (castecne). Konec ----- Zatim je to vsechno, snazil jsem se to udelat co nejjednodussi.