Il numero giusto dipende dall’oggetto della consegna
Un redattore che consegna un articolo e uno sviluppatore che controlla un file sorgente possono partire dallo stesso Markdown e voler misurare cose diverse. Nel primo caso interessano di solito titolo, paragrafi, elenchi e testo dei collegamenti. Nel secondo possono essere rilevanti anche segni di formattazione, indirizzi e codice. Non esiste una pulizia adatta a entrambi gli obiettivi senza una decisione iniziale.
Scrivi quindi una frase concreta prima di contare: “articolo come sarà letto, titolo incluso, esempi di codice esclusi”, oppure “intero sorgente consegnato”. Questa frase risolve più dubbi di una generica opzione chiamata “conteggio intelligente”. Il contatore di parole analizza la stringa che riceve; se incolli il sorgente, il risultato riguarda il sorgente. Una differenza rispetto all’anteprima non dimostra da sola che il motore abbia sbagliato a individuare le parole.
Titoli ed enfasi: le parole possono restare, le battute no
Il campione originale ## Gatto **nero** contiene un titolo e una parola enfatizzata. Il nostro motore misura diciassette caratteri e due parole quando riceve quei segni come testo. La versione leggibile Gatto nero contiene dieci caratteri e ancora due parole. Il confronto mostra un caso in cui le parole coincidono mentre le battute cambiano sensibilmente.
Non ricavare da questo esempio la regola “il Markdown non influisce sulle parole”. Vale soltanto per il campione. Alcune costruzioni aggiungono parole tecniche o indirizzi che il lettore non vede nella stessa forma. Inoltre un asterisco può avere un significato letterale dentro una spiegazione: rimuoverlo potrebbe cambiare il contenuto. CommonMark documenta una sintassi precisa per blocchi ed elementi interni. Per lavorare su un documento reale usa l’anteprima del suo ambiente e controlla i casi ambigui, anziché cancellare indiscriminatamente tutti i simboli.
Sorgente e versione leggibile misurati separatamente
| Campione | Caratteri del sito | Parole del sito | Che cosa comprende |
|---|---|---|---|
| ## Gatto **nero** | 17 | 2 | Sintassi del titolo e dell’enfasi |
| Gatto nero | 10 | 2 | Solo testo leggibile |
| [Leggi qui](https://esempio.test/guida) | 39 | 6 | Etichetta e URL |
| Leggi qui | 9 | 2 | Solo etichetta |
Il testo di un link e il suo indirizzo non sono lo stesso contenuto
Nel sorgente [Leggi qui](https://esempio.test/guida) compaiono sia l’etichetta sia l’indirizzo. La nostra prova locale restituisce trentanove caratteri e sei parole. Se il lettore vede soltanto Leggi qui, il corrispondente campione testuale ha nove caratteri e due parole. Le parole aggiuntive del sorgente derivano dal modo in cui il motore divide i componenti dell’indirizzo.
Se stai fatturando o limitando il testo editoriale, concorda se l’indirizzo sia incluso. In una guida tecnica può essere necessario mostrarlo integralmente; in un pulsante o in un collegamento incorporato può restare un’informazione di destinazione. Lo stesso vale per i riferimenti definiti altrove nel file. Una copia del solo corpo non deve aggiungere automaticamente tutte le definizioni finali. Controlla una voce alla volta e verifica il risultato nella versione pubblicata, specialmente quando un link contiene anche un titolo descrittivo.
I blocchi di codice richiedono un criterio autonomo
Un esempio di programma può contenere molte sequenze che sembrano parole: nomi di variabili, stringhe, commenti e comandi. Un conteggio linguistico non può stabilire se siano parte del lavoro editoriale, del materiale dimostrativo o di un allegato. Se il limite riguarda soltanto la prosa, escludi i blocchi di codice dalla copia misurata e annota questa scelta.
Il codice in linea può essere più difficile da separare. In una frase come “imposta timeout a cinque secondi”, il nome dell’opzione aiuta a comprendere l’istruzione; cancellarlo produce una frase incompleta. Puoi includerlo pur escludendo un lungo listato successivo, purché il criterio sia dichiarato. Evita anche di confondere una recinzione di codice con una citazione o un semplice rientro. Se il documento usa estensioni diverse da CommonMark, consulta l’anteprima effettiva: l’interpretazione del sorgente può dipendere dal sistema che lo pubblica.
Immagini, descrizioni alternative e didascalie
Il riferimento a un’immagine può contenere una descrizione alternativa e un percorso. Nessuno dei due coincide automaticamente con una didascalia visibile. Per un inventario dei testi di una pagina accessibile può essere opportuno misurare la descrizione alternativa in una voce separata; per il limite di un articolo può valere un accordo diverso. Il percorso del file, invece, non diventa prosa soltanto perché compare tra parentesi nel sorgente.
Prepara una piccola distinta: corpo dell’articolo, didascalie, testi alternativi e metadati. Questo evita che la stessa descrizione venga sommata due volte dopo una conversione. Se un’immagine contiene parole dentro il disegno, quelle parole non sono necessariamente presenti come testo nel Markdown. Il contatore non le ricava dal file grafico. Se rientrano nella consegna, trascrivile e identificane la provenienza; non usare il nome del file come stima del testo incorporato.
Preparare una copia leggibile senza perdere struttura
Apri una resa del documento nel sistema che dovrà utilizzarlo. Seleziona l’area concordata, copiala come testo e controlla titoli, elenchi e collegamenti. Questo percorso è adatto a una verifica editoriale, ma non garantisce che ogni programma trasferisca gli stessi separatori. Per un processo ripetuto può essere preferibile una conversione mediante un parser coerente con il formato scelto.
Non usare una sola espressione che elimini tutto ciò che sta tra parentesi: potresti cancellare una precisazione italiana, una formula oppure un contenuto che deve restare. Anche eliminare tutti i caratteri # o * può danneggiare esempi e simboli letterali. Una conversione affidabile distingue il ruolo sintattico dal carattere preso isolatamente. Dopo la conversione, rileggi almeno i passaggi con link, codice e citazioni: sono i punti in cui una copia apparentemente pulita può diventare meno fedele.
Tabelle ed estensioni non vanno date per scontate
Un file con estensione .md non rivela da solo tutte le regole usate dal progetto. Tabelle con barre verticali, note, metadati iniziali e altri elementi possono appartenere a estensioni del formato. Un sistema potrebbe mostrarli come una tabella o elaborarli come istruzioni; un altro potrebbe lasciarli come testo. Il totale del sorgente resta misurabile, ma non descrive necessariamente il contenuto finale.
Se l’articolo viene pubblicato in più ambienti, scegli una versione di riferimento e registra le esclusioni. I metadati con titolo, autore o categorie non devono entrare due volte quando il titolo viene già reso in pagina. Per una tabella, decidi se includere tutte le celle o soltanto quelle editoriali. Una colonna di codici prodotto può essere utile per il lettore e avere comunque un trattamento diverso nel preventivo. La scelta va motivata dal lavoro richiesto, non dalla forma più breve del conteggio.
Un controllo che separa errore di perimetro ed errore di calcolo
Conserva due copie distinte se ti servono sia il peso editoriale sia la consistenza del sorgente. Nominale chiaramente e misura entrambe con lo stesso metodo. Uno scarto grande concentrato nei link suggerisce che gli indirizzi siano entrati nel sorgente; uno scarto concentrato nei listati suggerisce una differenza di inclusioni. Questa osservazione permette di cercare un blocco preciso, senza modificare le parole del testo.
Prima della consegna ripeti il controllo su un titolo con enfasi, un collegamento e un blocco di codice scelti dal documento reale. Non serve che i numeri coincidano tra sorgente e versione leggibile: serve che ogni differenza sia spiegabile. Se il formato finale è HTML, la guida sul conteggio del testo HTML affronta un ulteriore passaggio: distinguere il codice della pagina dal contenuto effettivamente mostrato.
Fonti e verifiche
- CommonMark: specifica 0.31.2Esistenza di regole sintattiche distinte per blocchi, enfasi, collegamenti e codice; non tutte le estensioni sono parte dello stesso formato.
Controlli specifici di questa guida
- Calcolati caratteri e parole dei quattro campioni con analyze().
- Verificata la distinzione tra elementi sintattici nella specifica CommonMark aperta.
- Non attribuito al sito un parser Markdown: il comportamento descritto è il conteggio della stringa incollata.