Sziasztok!
Word DOC -> markdown konvertálás nagyszerűen működik a Pandoc-kal. Az MD-ből HTML és PDF generálás is működik. A PDF ág lenne most érdekes. A Typst CLI-ből is elérhető, a Pandoc konvertáláskor Typst template is használható.
Próbálom megérteni a Typst template felépítését, működését, de meg elég sok a homály.
Van itt a HUP-on valaki, aki md-ből tud csilivili PDF-et generálni, mert érti a szóban forgó template használatát?
Cz
- 459 megtekintés
Hozzászólások
subs.
(Én Asciidoc vonalon csinálok Doc-As-Code toolchaint, így nem tudok segíteni, de érdekel a téma)
Talisker Single Malt Scotch Whisky aged 10 years - o.k. Yamazaki is playing as well :)
- A hozzászóláshoz be kell jelentkezni
Nem ismerem a Typst projectet, viszont volt egyszer olyan feladatom, ami PDF-ekkel kapcsolatos.
Egy kurzus anyaga rengeteg PDF-ben volt kiadva, amiben nehez volt keresni. A ChatGPT a Pythonos PyPDF2-vel kb. 5 perc alatt adott olyan kodot, ami a megadott konyvtar osszes PDF-et betette egybe, amiben mar ment a ctrl-F, modositani is minimalisan kellett.
A Markdown eleg konnyu formatum, lehet, hogy irnek erre valami kodot, ami pont azt csinalja, ami nekem kell.
Egyebkent ha az egesz folyamat eleje Word doc, abbol PDF nyomtatoval meg LO Writerrel is nagyon konnyen kaphato PDF, en a Markdown fazist kihagynam az egeszbol.
A strange game. The only winning move is not to play. How about a nice game of chess?
- A hozzászóláshoz be kell jelentkezni
Ez egy online folyóirat, ahova a szerzők jól-rosszul követve a kiadott sablont, végül beküldik hozzánk az írásaikat, MS DOC-ban. Eddig ezt a DOC-ot formázta a kolléga, majd én kaptam meg, hogy gyártsak belőle HTML-t. LO Writer volt eddig a legjobb barátom, végül is éveken keresztül működött így az újság.
Mára annyival változott a helyzet, hogy a tanszék már nem fizet a szerkesztési munkáért, viszont a folyóirat nekünk presztízst jelent. Tehát 0 pénzből kell vinni tovább az ügymenetet.
Emiatt viszont szeretném a lehető legkevesebb időmet lekötni a felesleges dolgokkal. Néha a cikk jól nézett ki DOC-ban, de a HTML kimenet gyatra lett, ilyenkor szinte újra kellett szerkesztenem a dokumentumot. Ilyesmiket szeretnék elkerülni a markdown köztes állapottal.
Az MD szöveges alapú, azt a pár vezérlő karaktert mindenki meg tudja érteni, elég nehéz elrontani, ha valaki belegépel a kódba, a Pandoc-kal meg nagyon jól lehet konvertálni PDF-be.
Tegnap óta annyi történt, hogy aludtam rá egyet, ma reggel beugrott, milyen logika szerint működik a Typst template. Már vannak kezdeti sikereim. Úgy érzem, lesz belőle valami, majd leírom, mi jutok.
- A hozzászóláshoz be kell jelentkezni
esetleg nézd meg az AsciiDoc-ot.
Sokáig kerestünk valamilyen text alapú megoldást, ami nem olyan pilótavizsgás, mint a LaTeX de azért többet tud, mint egy Markdown.
Kb mostmár 2 éve dolgozunk vele. Alapvetően technikai dokumentációk készítésére. Főként ha csoportosan dolgozik több ember egy doksin, akkor jól jön, hogy simán verziómenedzselhető, mivel sima text. Egy halom szöveg alapú diagrammer markupot ismer pl. PlantUML, meg ilyen képlet hegesztőket.
Eléggé starightforward a HTML meg a PDF output is. Mindkettőre külön lehet stylingot összerakni.
Ilyen alapokon van egy ful static site generátor is mellá, az Antora.
Újabban ezzel gyártunk online help-et a rendszereinkhez.
Jól illeszthető egyébként egyedi toolchain-be is a dolog. Akár automatizált doksizás is megoldható vele.
Nekünk nagyon bejött, pedig a lehetőségeinek csak egy subsetjét használjuk ki egyelőre.
Talisker Single Malt Scotch Whisky aged 10 years - o.k. Yamazaki is playing as well :)
- A hozzászóláshoz be kell jelentkezni
Milyen programot használtok hozzá?
- A hozzászóláshoz be kell jelentkezni
hát elég változatos a dolog, mert többféle lehetőség is van.
Szerkesztésre IntelliJ-t meg VSCode-ot. Alapvetően linuxon használjuk (Fedora, Ubuntu, SuSE, Rocky).
Mindegyikben van Asciidoc plugin. Plusz PlantUML is.
Én az IntelliJ-s toolset-et favorizálom. A plugin fel van készítve az Antora-s site definíciók kezelésére is.
Parsolja az adoc fájlokat, értelmezi a doksi struktúrát, egész jó prediktív javaslatai vannak.
A Gracie plugin meg a Hunspell együttesen tök jó szövegellenőrzést biztosít.
Maga az asciidoc eszközkészlet több platformon is elérhető. Alapból Rubyban fejlesztették, de van Java-s meg JavaScript-es implementáció is. Eléggé kompatibilsek ezek (meglepő módon).
Ruby Gem-ként is felrakható, de linuxon a disztrók alapból tartalmazzák package szinten is.
Érdemes valami elkülönített, vagy projektre lokális installt csinálni. Különösen, ha használ az ember olyan extension-öket, amiknek van valami natív bindingja. Ilyen pl az, amelyikkel doksi generálás közben képes felszippantani git repo infókat, amiket populálni lehet attributumként a doksikba.
Ehhez a gem installjakor natív buildelést kell végezni. Linuxon, kernel frissítés után ezt rebuildelni kell.
Érdemes kidolgozni vmi saját doksi struktúrát, mert nagy doksik esetén fontos a konvencóik egységesítése, különösen, ha sokan dolgoztok egy doksi szetten. Az Asciidoc-nak és az eszközkészletnek (Asciidoctor, asciidoctor-pdf stb.) brutál jó részletes doksija van. Halom példával, use-case-zel.
Esetleg érdemes docker image alapú csomagolását kipróbálni.
Első körben mi helyi installos leosztásban használtuk/használjuk. Most van kialakítás alatt a konténer alapú toolset. Ebbe egy halom helyi dolgot is összetolok. Összes asciidoctor extension, használt fontok, PDF, meg CSS stylesheet-ek, doksi template-ek stb.
Mindez az Antora-s site-genráláshoz szükséges dolgokat is egyszerűsíteni fogja.
Az Antora multi repo-s, multi verziós site kezelése orbitál jó. Gyakorlatilag a fejlesztési repokba ki lehet jelölni külön Antora site content source pontokat, ahol a doksikba simán be lehet emelni a kész program forráskódokból részeket a dokumentáláshoz. Mindezt úgy, hogy nem kell duplikálni a forrásrészeket a doksihoz, elég a hivatkozás. Nagyon tuti kód taggelési lehetőségei vannak, tetszőleges syntax highlightert lehet használni.
A site genrálás után instant lehet publikálni HTTP serverre a dolgot. A build folyamatba be lehet kötni, hogy az egyes site content csomagokból csináljon PDF-et is. A layout része külön testreszabható. Van külön git repo, amiben a UI csomag van. Ezt totál szét lehet szerelni, testreszabni. Mondjuk az alap UI package, amit összeraktak is elég részletes. Kényelmesen lehet testreszabni. Külön ehhez a projekthez az ügyfél arculati kézikönyve meg az ott online arculatra lefektetett irányvonalaknak megfelelően csináltunk egy egyedi UI bundle-t.
Software help, vagy API dokumentálásra első osztályú szerintem.
Mi egy full implemetációs projektet dokumentáltunk ezzel az eszközkészlettel.
PID, SRS, SDD, User guide, Online help, install doksi, operation guide stb. Vagy 40 doksi.
Párszáz diagram, architektúra ábra, use-case, ER-diagram, Activity digram, State, Sequence, Gantt stb.
Pár link:
AsciiDoc
----------
https://asciidoc.org/
https://asciidoctor.org/
https://docs.asciidoctor.org/asciidoctor/latest/
https://docs.asciidoctor.org/asciidoc/latest/
https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/
https://leanpub.com/awesomeasciidoctornotebook/read#awesome-asciidoctor…
https://blog.mrhaki.com/2014/08/awesome-asciidoc-changing-highlightjs.h…
Antora
--------
https://antora.org/
https://docs.antora.org/antora/latest/
https://gitlab.com/antora/antora-assembler
https://coastsystems.net/en/blog/2022-01-04-antora/
Antora docs UI-hoz:
https://handlebarsjs.com/guide/#what-is-handlebars
PlantUML
----------
https://plantuml.com/
https://plantuml-documentation.readthedocs.io/en/latest/
https://real-world-plantuml.com/
https://crashedmind.github.io/PlantUMLHitchhikersGuide/index.html
https://kroki.io/
https://hub.docker.com/r/yuzutech/kroki
IntelliJ IDEA, Asciidoc plugin home
---------------------------------------
https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/index.html
Talisker Single Malt Scotch Whisky aged 10 years - o.k. Yamazaki is playing as well :)
- A hozzászóláshoz be kell jelentkezni
Nagyon köszönöm ezt a részletes leírást.
Közben feltettem az IntelliJ-t meg a plugint, elkezdtem ismerkedni vele.
- A hozzászóláshoz be kell jelentkezni
Ezért szeretek ide, a HUP-ra járni! Értelmes emberek érdekes válaszaiért :-)
A mostani lapszámot valószínűleg MD alapon hozzuk ki, de ránézek erre az asciidoc-ra, mert nagyon tetszik.
- A hozzászóláshoz be kell jelentkezni
fentebbi kommentben összeszedtem pár linket. Induláshoz bőven sok is :)
btw, az Asciidoctor meg az Antora online doksikat önmagával, azaz ezzel a toolsettel csinálják.
Pandoc-kal együtt kb határ a csillagos ég. Egy bizonyos szintig az asciidoc-ból lehet DOCX konvertálást is csinálni. Mondjuk ehhez kell egy ilyen template vagy boot referencia doksi, amiben össze vannak rakva a word-ös stílus dolgok. (Már ha valaki mazochista, vagy az ügyfél hisztizik, hogy neki word doksi kell)
Engem bazira beszippantott ez az egész Doc-As-Code irány. Lehet, hogy azért, mert több ezer doksit kellett már szerkesztenem az évek alatt és orbitál szívás tud ez lenni ilyen Word és társai eszközökkel.
Egész más dimenzióba emeli a problémát ez az irány. Nem look-and-feel-el szív az ember folyton, meg az ilyen olyan diagram szerkesztgetőkkel (Visio, SmartDraw, diagram.io és társai).
Azért az nem gyenge, hogy egy content forrásból egy halom féle kimenetet le lehet gyártani. Mindemellett minden progamozásnál megszokott eszköz rendelkezésre áll verziózáshoz, release menedzsmenthez, csoport munkához.
Érdemes kicsit kitekinteni a világnak erre a részére is :)
Ha bővebben érdekel vmi, szivesen segítek, amiben tudok.
Talisker Single Malt Scotch Whisky aged 10 years - o.k. Yamazaki is playing as well :)
- A hozzászóláshoz be kell jelentkezni
Én html-t generáltam és headless chrome-mal nyomtattam pdf-et. Elvileg azt kapod, amit a html-ben látsz, de sok nyűgje volt, és végül elengedtem.
- A hozzászóláshoz be kell jelentkezni
+1
html->puppeeter->ghostscript, hogy pdfA3 legyen.
Működik, nincs vele bajom.
- A hozzászóláshoz be kell jelentkezni
en a minap ilyet csinaltam:
pandoc valami.md --pdf-engine=xelatex --template=template.tex -o valami.pdftemplate.tex:
\documentclass[10pt]{article}
\usepackage[margin=1in]{geometry}
\usepackage{multicol}
\usepackage{parskip}
\usepackage{hyperref}
\usepackage{graphicx}
\setlength{\columnsep}{20pt}
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}
}
\begin{document}
\begin{multicols}{2}
$body$
\end{multicols}
\end{document}
Ez csak sima ketoszlopos valami, ujsagcikkeknek.
- A hozzászóláshoz be kell jelentkezni