Pentru cine este

Documentația tehnică, cu tot codul intact

Clean Clipper citește limbajul de pe pagina însăși – clasa blocului, elementul părinte, marcajul lăsat de evidențiatorul site-ului – și îl scrie pe gard. Pe un corpus tehnic de nouă pagini, eticheta a supraviețuit în 73 de blocuri din 156, față de 20 și 0 la celelalte două motoare măsurate. Restul paginii ajunge în Markdown obișnuit, fără bara laterală.

Ce se rupe la copiere

O documentație este în cea mai mare parte cod, și exact partea aceea o strică majoritatea clipperelor. Blocul ajunge gol, fără etichetă: în Obsidian se vede ca o pată gri uniformă, iar într-un depozit trece prin review fără nicio culoare. Așa că redeschideți fiecare notiță ca să scrieți de mână js, python sau bash deasupra fiecărui gard. Pe o documentație de treizeci de pagini asta înseamnă o seară pierdută reparând ceva ce exista deja pe pagina originală.

Restul preluării nu stă mai bine. Selectorul de versiune, bara laterală și lista „pe această pagină” aterizează în mijlocul textului, iar un tabel de parametri se turtește pe o singură linie fiindcă o celulă conținea un exemplu de cod. Peste trei luni căutați o opțiune de API prin notițele proprii și dați întâi peste trei copii ale meniului. Notița există, dar nu se mai lasă recitită.

A treia pierdere este versiunea. O documentație are versiuni, adresa ei aproape niciodată: pagina pe care ați citit-o pentru v4 devine tăcut pagina lui v6, cu un parametru redenumit și o opțiune scoasă, iar semnul de carte se deschide în continuare – numai că spune altceva. Nicăieri în notițele dumneavoastră nu scrie față de ce versiune a fost luată decizia. Un fișier care poartă în cap adresa și data declarată de pagină răspunde la întrebarea aceasta peste un an; un semn de carte nu a răspuns niciodată.

Ce se schimbă în notiță

• Blocul iese ca ```js, nu gol – evidențierea funcționează în Obsidian, VS Code și pe GitHub din clipa în care lipiți
• Limbajul este citit de pe pagină – clasa blocului, elementul părinte, marcajul evidențiatorului – niciodată ghicit din cod
• Un tabel de parametri cu cod într-o celulă își păstrează rândurile, în loc să se turtească
• Linkurile de referință devin note [^1], cu definițiile adunate la finalul fișierului
• Bara laterală, selectorul de versiune și lista „pe această pagină” sunt tăiate, nu convertite
• Codul în linie rămâne cod în linie, inclusiv în titluri și în celulele tabelelor
• Extragerea rulează pe DOM-ul randat, așa că o documentație construită în JavaScript ajunge exact așa cum o vedeți pe ecran
• Câmpul extraction spune pe ce cale a venit textul: dom sau jsonld-articlebody
• Pe Reddit firul își păstrează structura și scorul fiecărui comentariu – acolo stau jumătate din răspunsurile reale despre o bibliotecă

## Trimiterea facturii

Încărcarea se face cu tokenul obținut prin OAuth:

```bash
curl -X POST "https://api.anaf.ro/prod/FCTEL/rest/upload?standard=UBL&cif=12345678" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @factura.xml
```

| Parametru | Valoare |
| --- | --- |
| `standard` | UBL, CN, CII sau RASP |
| `cif` | codul fiscal al emitentului |

Cum se pune la punct pentru documentație

Cinci minute o singură dată, apoi rămâne scurtătura. Setările implicite sunt gândite pentru citit articole; o documentație cere alt tipar de nume, niciun câmp de autor și nicio imagine.

1. Instalați extensia și fixați pictograma în bara de unelte. Clic dreapta pe pictogramă, apoi Opțiuni, ca setările să se deschidă într-o filă.
2. Puneți ce face clicul pe pictogramă pe „salvează în dosar”. Fereastra de previzualizare ajută cât învățați unealta și încurcă după aceea; fără ea, o preluare este o singură apăsare.
3. Alegeți dosarul. Indicați un dosar aflat deja sub control de versiune – de pildă docs/preluari din depozitul la care lucrați. Browserul cere confirmarea o singură dată și ține minte permisiunea pentru profilul acela.
4. Puneți tiparul de nume pe {domain}-{title}. Patru cadre de lucru au fiecare câte o pagină numită „Introducere”; fără domeniu în nume, a doua ajunge introducere-2.md, a treia introducere-3.md, și nu mai știți a cui este care.
5. În secțiunea de frontmatter păstrați source și extraction și opriți author. Documentația este rareori semnată, iar un câmp gol în fiecare fișier este zgomot pe care oricum îl veți șterge.
6. Puneți imaginile pe „ignoră”. O captură din alt IDE nu se caută cu grep, iar linkul ei trimite la o rețea de livrare care se va muta.
7. Deschideți chrome://extensions/shortcuts și verificați că Alt+Shift+M este într-adevăr legat. Dacă l-a luat altă extensie, de acolo îl luați înapoi.

Setările potrivite unui programator

Acestea sunt valorile care merită schimbate față de cele implicite, cu motivul pentru care fiecare contează la o documentație tehnică, nu la citit în general.

Rulați migrarea înainte de a porni serviciul:

```
./bin/migrare --mediu productie
```

```powershell
Get-Content ./jurnal.txt -Tail 50
```

Al doilea gard purta `class="language-powershell"`. Primul nu purta nimic
și rămâne gol, în loc să primească o etichetă ghicită.

Trei situații de lucru

Versiunea față de care s-a construit efectiv

Sunteți pe ramura v4 a documentației unui cadru de lucru, la pagina despre un parametru de configurare redenumit în v5. Apăsați Alt+Shift+M. Fișierul aterizează ca exemplu-dev-referinta-configurare.md în docs/preluari, cu source care arată spre adresa cu /v4/ și cu data declarată de pagină în cap.

Peste opt luni parametrul se poartă altfel în producție și nimeni nu mai știe de ce a fost pus așa. Preluarea este în depozit, în același interval de commituri cu schimbarea, și spune față de ce versiune a documentației s-a luat decizia. Adresa vie servește acum v6 și nu mai pomenește deloc parametrul.

Firul de forum care a rezolvat de fapt problema

Documentația oficială descrie drumul fericit, iar soluția pentru cazul dumneavoastră stă într-un fir de pe Reddit, la al patrulea nivel de comentarii, unde răspunsul bun are 140 de puncte și stă sub unul greșit cu 30. Preluați firul: regula pe site îl trimite în fire, iar structura vine ca citate imbricate, cu scorul lipit de fiecare mesaj.

Scorul este exact partea care contează la recitire. O copiere obișnuită a aceluiași fir pierde cu totul semnalul de ordonare și rămâneți cu cinci păreri între care nu mai puteți deosebi pe care a confirmat-o comunitatea.

Un tabel de parametri, direct în cererea de fuzionare

Ghidul de instalare are un tabel cu optsprezece variabile de mediu, dintre care trei au un exemplu de cod în celulă. Selectați tabelul pe pagină, preluați selecția și lipiți Markdownul în descrierea cererii de fuzionare. Este randat ca tabel, pentru că este tabel GFM, nu o captură.

Pe corpusul tehnic de cincisprezece tabele, serializatorul acesta a păstrat douăsprezece, acolo unde fiecare dintre motoarele comparate a păstrat șapte. Celulele care rup convertoarele generice sunt tocmai acestea: cele cu cod sau cu o listă înăuntru.

Față de cum se face acum

Fiecare dintre metodele de mai jos funcționează, și fiecare este ceea ce face cineva din echipa dumneavoastră chiar în clipa asta. A treia coloană este prețul real, inclusiv al nostru.

Când nu iese cum trebuie

De ce este gardul meu de cod gol?

Pentru că pagina nu a spus în ce limbaj este. Clean Clipper citește limbajul din clasa lăsată de evidențiatorul site-ului; nu se uită la cod ca să ghicească. Un exemplu stilizat de mână, fără clasă, dă un gard gol, și acesta este rezultatul cinstit: o etichetă python ghicită pe un fragment de shell este mai rea decât lipsa ei, fiindcă atunci evidențierea colorează cu încredere lucruri greșite.

De ce lipsește jumătate din ghid?

Aproape întotdeauna din cauza filelor sau a unui acordeon. Extensia convertește ce a randat efectiv browserul, iar conținutul unei file care se încarcă abia la clic nu există în DOM până nu dați clicul. Deschideți fila, desfășurați secțiunea și abia apoi preluați – sau preluați o dată pentru fiecare variantă. Unde site-ul randează toate filele și le ascunde din CSS, ele ajung toate, una după alta.

De ce spune că nu există articol?

O consolă de test a unui API, o pagină de rezultate sau un index de pachete este alcătuită mai ales din etichete de link, iar extensia le refuză intenționat: dacă peste aproximativ un sfert din caracterele extrase stau în interiorul unor linkuri, răspunde „nu există articol” în loc să vă dea trei sute de intrări. Refuzul acesta este și motivul pentru care ponderea ei de „text util” iese mai mică decât la motoarele care întorc mereu ceva.

Ce înseamnă extraction: "jsonld-articlebody" în fișierul meu?

Că pagina și-a livrat textul în datele structurate, dar nu a mai apucat să îl randeze în DOM, așa că textul a fost citit din datele structurate. Este consemnat, nu ascuns, fiindcă cele două căi pot să difere: uneori copia din datele structurate este o versiune anterioară, alteori este singura completă. Când vedeți valoarea aceasta, merită o privire pe original înainte de a vă baza pe text.

Ce nu face

Nu ghicește limbajul unui bloc pe care pagina nu îl etichetează: acolo unde site-ul randează cod fără clasă, gardul rămâne gol, și asta este intenționat – o etichetă inventată costă mai mult decât una lipsă. Nu parcurge un site întreg de documentație: o pagină pe rând, cea pe care vă aflați, fără crawler și fără procesare în lot. Nu descarcă scheme și nici capturi de ecran, imaginile rămân linkuri către site-ul original. Iar pe paginile protejate de browser, cum sunt chrome:// și magazinul de extensii, nu rulează deloc.

Întrebări