Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

API documentation is missing an explanation of CMARK_NODE_CUSTOM_BLOCK and CMARK_NODE_CUSTOM_INLINE

Aperta Adatta ai principianti
  • Qualcosa non va?
#441 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
68/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
c
Ambito
documentation

Direzione di ricerca

Inizia da man/man3/cmark.3 e individua la documentazione di cmark_node_type e dell’API custom-node, quindi confrontala con la voce corrispondente in changelog.txt. Il lavoro è completato quando la documentazione spiega che CMARK_NODE_CUSTOM_BLOCK e CMARK_NODE_CUSTOM_INLINE vengono inseriti dai filtri, non vengono generati dal parser, e descrive i relativi figli, il testo letterale e il comportamento on-enter/on-exit.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

The API documentation for cmark (e.g. in the cmark.3 man page) does not explain the
purpose or proper use of the CMARK_NODE_CUSTOM_BLOCK and CMARK_NODE_HTML_INLINE constants from the cmark_node_type enum. (Actually, it does not explain the purpose or use of any of the cmark_node_type constants; but all the others correspond fairly obviously to blocks or inlines in the CommonMark spec.)

I see that the changelog contains some description of them:

  • [API change] Added CUSTOM_BLOCK and CUSTOM_INLINE node types.
    They are never generated by the parser, and do not correspond
    to CommonMark elements. They are designed to be inserted by
    filters that postprocess the AST. For example, a filter might
    convert specially marked code blocks to svg diagrams in HTML
    and tikz diagrams in LaTeX, passing these through to the renderer
    as a CUSTOM_BLOCK. These nodes can have children, but they
    also have literal text to be printed by the renderer "on enter"
    and "on exit." Added cmark_node_get_on_enter,
    cmark_node_set_on_enter, cmark_node_get_on_exit,
    cmark_node_set_on_exit to API.

But that information really should be in the API documentation, not in the changelog - without it, the API documentation cannot be understood. And because the changelog uses the abbreviation CUSTOM_BLOCK instead of spelling out CMARK_NODE_CUSTOM_BLOCK in full, searching for CMARK_NODE_CUSTOM_BLOCK in the repository will never bring up that changelog entry, making it difficult for developers to work out what it was intended to do.

If the man page is the only place that would need updating, then I'd be happy to create a PR to add the changelog information to the man page, if desired.

Lingua principale
C
Stelle
2k
Fork
700
Merge medio
3g 9h
PR unite (30g)
5

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di commonmark/cmark

Tutte le issue di commonmark/cmark

Issue simili

Altre issue su C

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.