hzoltan blog

Mindig probléma a kódrészletek, vagy egyszerűen csak logikai szabályok, esetleg pszeudókód jellegű leírások beemelésének módja, egy nem elsősorban a technikai hallgatóság számára készülő anyagba, ugyanakkor néha megkerülhetetlen (legalább SQL query-k szintjén).

De facto a szabvány formátum persze a Microsoft Word doc, vagy docx (Sajnos a mára már egy mellőzött dokumentumkészítési rendszer lett az üzleti világban, pedig használatával nagyon igényes és nagyon jól változáskövethető állományok készíthetőek. Ennek oka lehet, hogy laposabb a tanulási görbéje és vannak korlátai, pl. nincs doc/docx typeset, így a Word-ben kezelhető dokumentumok létrehozása kicsit körülményesebb. Ettől függetlenül, ha időt szán rá az ember, akkor nagyon hatékony…). Az is igaz, hogy egyre több helyen lépnek túl a Word dokumentumok káoszán és váltanak valamilyen web-alapú megoldásra (pl. Atlassian Confluence), de a doc/docx, rosszabb esetben az ezekből generált PDF sok helyen még mindig az alap dokumentációs forma, így ebből kiindulva kellett egy standardizálható megoldást találni…

Aki sok szakirodalmat olvasott az észrevehette, hogy többé-kevésbé kialakult már egy jelölési konvenció ezekben a könyvekben (legalábbis kiadónként/sorozatonként egységes), de az üzleti dokumentációk és doc/docx formátum esetében ezek nem feltétlenül használható (ötleteket ellenben lehet belőlük meríteni :).

Személy szerint egy gyors és egyszerű megoldásra törekedtem, ami az alábbi tulajdonságokkal bír:

• a kódrészlet szerkeszthető marad, formázási lehetőségekkel (képernyőképek kiestek),
• a kódrészlet elkülönül a dokumentum többi részétől (mind vizuálisan, mind a formázási szabályok tekintetében).

Először is kell egy monospaced font, ami lehetőség szerint az Office által (is) alapértelmezetten támogatott (talán a legjobb választás a Courier New Windows környezeten, esetleg valamely az itt találhatóak közül). Az ilyen betűtípus nemcsak ezért jó, mert jellemzően elüt a normál font-októl, hanem mert programkód esetén annak olvashatóságát is segíti és nem mellesleg nekem tetszenek is :).

The sys­tem fonts Courier, Monaco, and Con­so­las are ex­am­ples of mono­spaced fonts, so named be­cause every char­ac­ter is the same width. Most other fonts are pro­por­tion­ally spaced, mean­ing the char­ac­ters vary in width.

(from: https://practicaltypography.com/monospaced-fonts.html)

A kódot érdemes WordPad Document objektumként beemelni a Word állományba, így kellően elkülönül majd a dokumentum többi részétől. Tapasztalataim szerint ez egy jól működő koncepció, amennyiben egy oldalnál kevesebb a megjelenítendő szöveg – az ilyen objektum tartalma nem tördelődik automatikusan!
Ha syntax highlight is kell (márpedig azért úgy az igazi), akkor persze kicsit problémásabb a dolog, de kis beállítgatás után remekül fog működni ez is.

Erre a célra én Notepad++ -t használok, amit ugyan nem kifejezetten szeretek (inkább PSPad, vagy még inkább Sublime :), de ingyenes, sok minden jól automatizálható benne és jelentős közösség is szerveződött köré, továbbá a legtöbb zárt hálózaton is elérhető a Total Commander mellett. Alapesetben én ezt is – mint minden más plain text editort – sötét háttér/világos karakterek beállítással használom, ez viszont probléma ha syntax highlight-ot is át akarunk másolni innen (átemelődik/bekavar a háttér). Sajnos a Notepad++ nem támogatja, hogy valamilyen hotkey binding-al lehessen témákat váltani, így más megoldás kellett, elkerülendő a manuális állítgatásokat (esetleg külön Notepad++ instancia fenntartását erre a célra). Szerencsére egy néhány soros AutoHotKey script-tel mindez megoldható:

Miről is van szó:

• egy billentyűkombinációhoz beállításra kerül a szokásos téma (jelen esetben az ‘Obsidian’) – <Alt>+<1>
• egy másik billentyűkombinációhoz pedig egy olyan, amiből a syntax highlight jól átemelhető (fehér háttér és default téma) – <Alt>+<2>

A fenti megoldás Notepad++ verziónként módosulhat, de az alábbi leírás alapján könnyen átírható:

Explained:

1. #IfWinActive, ahk_class Notepad++ makes sure the shortcuts only trigger while Notepad++ is the active window, so as not to have unexpected behavior while other windows are active.
2. !1:: defines an action for Alt+1. ! stands for Alt, ^ for Ctrl, + for Shift, and # for Win. They can be combined (order insignificant) like this: ^+k:: for Ctrl+Shift+k.
3. {ALT}t brings up the „Settings” menu.
4. s{ENTER} selects „Style Configurator…”
5. {HOME} resets the selected theme to the top item (so as to always count from the top).
6. s or ss selects themes by cycling through by starting letters. You can also use a bunch of {DOWN}s, but that’s more prone to breaking when styles are added or removed from the list.
7. {TAB} seven times brings us to Save and Close, after which we hit {ENTER}.

(from: https://superuser.com/questions/592072/shortcut-to-switch-between-themes-in-notepad)

Ezt követően már csak ki kell másolni a kívánt kódrészletet a NppExport plugin / ‘Copy all formats to clipboard’ paranccsal és készen is vagyunk. A kezdeti beállítások után mindez néhány kattintás csupán :).

(from: saját forrás, példa egy beillesztett kódrészletre, Python, syntax highlight-al – Word nyomtatási kép)

Megosztás: on Twitter on Facebook on LinkedIn