Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

the documentation about metadata is a bit fragmented #4584

Open
danse opened this issue Apr 23, 2018 · 5 comments
Open

the documentation about metadata is a bit fragmented #4584

danse opened this issue Apr 23, 2018 · 5 comments
Labels
docs

Comments

@danse
Copy link
Contributor

danse commented Apr 23, 2018

The documentation about metadata is currently part of a section about Pandoc's markdown while it could be a dedicated section with info about readers and writers in order to avoid duplication. Here i express some doubts about the handling metadata are supposed to receive, while here @jkr has doubts about how to document metadata handling for the DOCX writer.

Metadata are part of the data model, and supported to various degrees by the different readers and writers, therefore i would suggest to document them in a section where the intended semantic is explained first, followed by sections about metadata handling in specific readers or writers.
@mb21 mb21 added the docs label Apr 23, 2018
@mb21
Copy link
Collaborator

mb21 commented Apr 23, 2018 •
edited
Loading

I tend to agree... part of the story is also in the templates section.

Hopefully, I get to work on #1960 soon. Then we could consider moving the Metadata blocks extension section from the markdown extensions to the general extensions part...

See also the wiki for some further links to potential changes in the future...

@danse danse mentioned this issue May 2, 2018
Closed
@Zack-83
Copy link

Zack-83 commented Jul 17, 2018 •
edited
Loading

It would be very helpful to have a comparison table showing the fields which can be traded between different formats, with particular regard to metadata information. That would greatly help to make it clear, what Pandoc presently can and what it cannot, and which "granularity" is provided.

Let me begin with what I learnt so far:

--------------------------------------------------------------------------------------------------------
HTML                       LaTeX             DOCX (style or position) DOCX (doc properties) Dublin Core
-------------------------- ----------------- ------------------------ --------------------- ------------
<title>                    \title            1st position             title                 dc:title

<meta name="author">       \author           2nd position             author                dc:creator

<meta name="dcterms.date"> \date                                      date (overwritten)    dcterms:date

<meta name="abstract">     \begin{abstract}  3rd position                      

                           \tableofcontents  4th position

<body>                     \begin{document}

<h1>                       \section          Header 1

<h2>                       \subsection       Header 2

<br>                       \newline

<p>

<em>                       \emph

<strong>

<table>                    \begin{longtable} Table

etc.
-------------------------------------------------------------------------------------------------------

Does anybody have a more complete table? Or who would like to contribute to write one?

@danse
Copy link
Contributor Author

danse commented Jul 17, 2018

@Zack-83 it's a good initiative, but i am afraid that maintaining such a table would be too demanding and it will end up getting outdated. Also the relational, tabular structure does not suit the actual data model used within pandoc, which is based on the native format, and readers and writes from and to every supported format.

About this, i admit that i have some doubts about the data model for metadata. As far as i understood skimming through Definitions.hs in pandoc-types, there is no fixed set of metadata: they are simply strings that are managed by convention. Do we want to turn them into a defined set?

@mb21
Copy link
Collaborator

mb21 commented Jul 17, 2018

btw, you can see which are used how with e.g. pandoc -D latex

@jgm
Copy link
Owner

jgm commented Jul 19, 2018 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@jgm @mb21 @danse @Zack-83