Make text format non-normative. #3131
Conversation
|
And also added URIs. |
| This file is a copy of the associated template file, but extended with the translations in the specified language. | ||
| The pattern \filename{<language>} stands for the ISO 639-1 language code, e.g. \filename{de} or \filename{en}. | ||
| \end{enumerate} | ||
|
|
||
| The files consist of a header and a body. | ||
| The detailed format of these files is described in \href{https://www.gnu.org/software/gettext/manual/gettext.pdf}{GNU gettext}. |
There was a problem hiding this comment.
Maybe a normal citation would be better? (Currently, we only use \href directly in revisions.tex.)
There was a problem hiding this comment.
Maybe a normal citation would be better? (Currently, we only use
\hrefdirectly in revisions.tex.)
Could do, but I wanted to be as close as possible to the markdown of the proposed specification text.
Another possibility is to to use href more; I can understand that we want to show the complete hyper-link text for Modelica-links in order to make modelica.org more visible - but for external links I don't see a similar reason.
There was a problem hiding this comment.
Could do, but I wanted to be as close as possible to the markdown of the proposed specification text.
Why?
There was a problem hiding this comment.
Another possibility is to to use href more; I can understand that we want to show the complete hyper-link text for Modelica-links in order to make modelica.org more visible - but for external links I don't see a similar reason.
Of course, one reason to use normal citations is that having a bibliography adds value to the document by itself. However, in order to provide that value, the bibliography should be complete in the sense that there aren't any additional references hiding in the document.
There was a problem hiding this comment.
Could do, but I wanted to be as close as possible to the markdown of the proposed specification text.
Why?
Because there was a proposed specification text in markdown, and I assumed people thought that it was ok - so the goal was to copy that into the normal specification while preserving everything.
There was a problem hiding this comment.
Note that one of the nice benefits of using a proper reference is that we get the back-references in the bibliography.
There was a problem hiding this comment.
Because there was a proposed specification text in markdown, and I assumed people thought that it was ok - so the goal was to copy that into the normal specification while preserving everything.
That goal could work in some cases, but I don't find it realistic or helpful in gerneral. The design documents are of most value before getting to the MCP stage of preparing actual specification changes. After that point, I think we want maximum freedom of responding to reviewer feedback on the specification changes, while only making sure that the markdown design documents remain a correct description of the design going into the specification.
The design documents should also serve as a deeper background for future reference, and as such the style and scope of presentation could differ significantly from the specification changes. Therefore, I'd generally not expect the formulations in the specification changes to be direct copies of formulations in the design documents.
There was a problem hiding this comment.
Obviously we can update it, but I wanted the starting point to be as close to it as possible.
|
@gkurzbach was this what you wanted? |
HansOlsson
added
the
MCP
I believe this is the part you wanted to make non-normative, right?