A bunch of metadata usage questions

[Moacir]

Hey all,

I'm very, very close to being able to achieve the convergence of keeping
one mmd file that becomes both my course website and syllabus pdf that
is also decoupled from each instance of a course, but I had a bunch of
questions, etc., about how to maybe better use the metadata:

1. Metadata don't seem to be available to transcluded files. I think FTP
has mentioned in other threads that that is the point—transclusion
doesn't care if the file exists or not, so it shouldn't send more
information to it. That would be useful, though, because now, for
example, I have:

<!-- \iffalse -->
{{sections/navbar.html}}
<!-- \fi-->

to create a navbar for the website, but that html file needs to be
edited by hand (or by jquery in the htmlfooter metadata) to feed in
values like "title" for the navbar-brand.

2. Metadata aren't available in certain places in the markdown syntax.
I'd like to do something like this:

---
githuburl: http://github.com/some/repo

...

For more information, please see [the github repo]([%githuburl]).

Neither that, nor

[the github repo]: [%githuburl]

yield the value for that key. I'm trying to figure out how to do that in
post-processing, but I think it'd be a useful thing to do, because while
boilerplate ("please see...") doesn't change from course to course, the
url to the syllabus repo will. Being able to control that wholly in the
metadata would be great.

3. There's no way for me to access the metadata in javascript

At least not that I can think of. I would've liked to have at the end of
my file something like:

<!-- \iffalse -->
<script>
$('#navbar-brand').text("[%title]");
</script>
<!--\fi-->

But of course mmd just goes past it. If I do <script markdown=1>, then a
whole different series of issues follows (htmlization of quotes), and I
still don't get to access the value in [%title].

4. mmd2tex latexifies the metadata, too.

This is surely a feature, but it was an unexpected one. I suspected that
I could define githuburl as above and expect it to be available as
\def\githuburl{http://github.com/some/repo} and not as http:/\slash
github.com\slash ...

I've gotten around most of these w/ post-processing, but I was wondering
if these might not be things to think about for future releases. As it
is, mmd is great, and I've found it playing a buch bigger role in my
life now that I understand how to manipulate the metadata better (esp in
latex templates and htmlheader and htmlfooter).

--m

--
Moacir
moa...@gmail.com

[neuroman53]

Not to be or sound obtuse, but have you tried the MMD CMS? I might have misunderstood your questions, but from my reading, it sounds like it could solve your issues with header, footer, and metadata

[Fletcher T. Penney]

On 12/12/16 8:03 PM, Moacir wrote:
> Hey all,
>
> I'm very, very close to being able to achieve the convergence of keeping
> one mmd file that becomes both my course website and syllabus pdf that
> is also decoupled from each instance of a course, but I had a bunch of
> questions, etc., about how to maybe better use the metadata:
>
> 1. Metadata don't seem to be available to transcluded files. I think FTP
> has mentioned in other threads that that is the point—transclusion
> doesn't care if the file exists or not, so it shouldn't send more
> information to it. That would be useful, though, because now, for
> example, I have:
>
> <!-- \iffalse -->
> {{sections/navbar.html}}
> <!-- \fi-->
>
> to create a navbar for the website, but that html file needs to be
> edited by hand (or by jquery in the htmlfooter metadata) to feed in
> values like "title" for the navbar-brand.

Not sure I follow. Transclusion happens first -- making one big
document. At that point, the same metadata applies to the entire
document, regardless of which transcluded file the source started in.

Separately, the metadata in a file that *is transcluded by another file*
is ignored. One can only have one set of metadata.

> 2. Metadata aren't available in certain places in the markdown syntax.
> I'd like to do something like this:
>
> ---
> githuburl: http://github.com/some/repo
>
> ...
>
> For more information, please see [the github repo]([%githuburl]).
>
> Neither that, nor
>
> [the github repo]: [%githuburl]
>
> yield the value for that key. I'm trying to figure out how to do that in
> post-processing, but I think it'd be a useful thing to do, because while
> boilerplate ("please see...") doesn't change from course to course, the
> url to the syllabus repo will. Being able to control that wholly in the
> metadata would be great.

True -- metadata variables are only parsed in the same places that any
Markdown syntax is parsed. Which does not include inside URLs. This is
standard Markdown/MultiMarkdown behavior. I don't anticipate changing this.

The "proper" approach here would be to store your link references in
separate files -- that way you can transclude the specific link
definitions needed, e.g.:

Link to the [project page].

One file can include:

[project page]: http://foo.bar/project1

Another can include

[project page]: http://foo.bar/project2

> 3. There's no way for me to access the metadata in javascript
>
> At least not that I can think of. I would've liked to have at the end of
> my file something like:
>
> <!-- \iffalse -->
> <script>
> $('#navbar-brand').text("[%title]");
> </script>
> <!--\fi-->
>
> But of course mmd just goes past it. If I do <script markdown=1>, then a
> whole different series of issues follows (htmlization of quotes), and I
> still don't get to access the value in [%title].

You're on your own with Javascript. ;) But again, Markdown, and
therefore MMD, doesn't screw with the contents of <scripts>.

> 4. mmd2tex latexifies the metadata, too.
>
> This is surely a feature, but it was an unexpected one. I suspected that
> I could define githuburl as above and expect it to be available as
> \def\githuburl{http://github.com/some/repo} and not as http:/\slash
> github.com\slash ...

Not sure what you're asking for here. MMD has to convert metadata into
the proper "character escaping" for the output format, with a few
exceptions that are handled in the code. You can always modify this
behavior however you like in the source and compile your own custom version.

> I've gotten around most of these w/ post-processing, but I was wondering
> if these might not be things to think about for future releases. As it
> is, mmd is great, and I've found it playing a buch bigger role in my
> life now that I understand how to manipulate the metadata better (esp in
> latex templates and htmlheader and htmlfooter).

Glad it's been helpful... I realize that there are a few edge cases
where someone needs something that truly can't be done in MMD (it's
nowhere near turing complete. ;) But I do feel it can do the vast
majority of things for the vast majority of users (within reason).

Fletcher


--
Fletcher T. Penney
fletche...@gmail.com

[Moacir]

On Sat, Dec 17, 2016, at 16:29, Fletcher T. Penney wrote:

> Glad it's been helpful... I realize that there are a few edge cases
> where someone needs something that truly can't be done in MMD (it's

That was what I was wondering: how edge my case was. I don't want to go
down the CMS route since the goal here was just a sort of template (for
a syllabus) that I could share with friends so they could make their own
very quickly.

> Not sure I follow. Transclusion happens first -- making one big
> document. At that point, the same metadata applies to the entire
> document, regardless of which transcluded file the source started in.

OK. This is what I find confusing. I have a pair of test documents:

main.md:

foo: bar

This is the first paragraph. foo is [%foo].

{{p2.html}}

p2.html:

<div markdown=1>
<p markdown=1>This is the *second* paragraph. Foo is [%foo]</p>
</div>

When I run mmd on this, the second instance of [%foo] (inside p2.html)
gets changed to "bar." This is expected behavior—though it took a bit to
suspect that the "markdown=1" needs to be nested.

When I add, however:

<nav class="navbar navbar-inverse navbar-fixed-bottom" markdown=1>
<div class="container-fluid" markdown=1>
<div class="navbar-header" markdown=1>
<button aria-expanded="false" class="navbar-toggle collapsed"
data-target="#navbar" data-toggle="collapse" type="button">
<span class="sr-only">Toggle Navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="#" markdown=1>[%foo]</a>
</div>
</div>
</nav>

to p2.html, then that second [%foo], inside a.navbar-brand, does not get
converted. I imagine this is because <a> is not block-level?

In this case, it's clear I misunderstood how tranclusion works, and this
might just be another edge case. Like I said, I have javascript fixing
this already, but, yeah.

> The "proper" approach here would be to store your link references in
> separate files -- that way you can transclude the specific link
> definitions needed, e.g.:

Nice. That's a good idea. It means yet another place where changes have
to be made to the template, but at least it'll create clean links. My
current solution is awful.

Thanks!

--m

--
Moacir
moa...@gmail.com

[Fletcher T. Penney]

On 12/18/16 3:37 PM, Moacir wrote:
>> Glad it's been helpful... I realize that there are a few edge cases
>> where someone needs something that truly can't be done in MMD (it's
>
> That was what I was wondering: how edge my case was.

Pretty far down the edge. ;)

> When I add, however:
>
> <nav class="navbar navbar-inverse navbar-fixed-bottom" markdown=1>
> <div class="container-fluid" markdown=1>
> <div class="navbar-header" markdown=1>
> <button aria-expanded="false" class="navbar-toggle collapsed"
> data-target="#navbar" data-toggle="collapse" type="button">
> <span class="sr-only">Toggle Navigation</span>
> <span class="icon-bar"></span>
> <span class="icon-bar"></span>
> <span class="icon-bar"></span>
> </button>
> <a class="navbar-brand" href="#" markdown=1>[%foo]</a>
> </div>
> </div>
> </nav>
>
> to p2.html, then that second [%foo], inside a.navbar-brand, does not get
> converted. I imagine this is because <a> is not block-level?

Correct -- MMD only recursively goes into certain HTML elements. You'll
have to dig through the source for an exhaustive understanding. Or
trial and error.


F-


--
Fletcher T. Penney
flet...@fletcherpenney.net

[Moacir]

On Sun, Dec 18, 2016, at 17:35, Fletcher T. Penney wrote:

> Correct -- MMD only recursively goes into certain HTML elements. You'll
> have to dig through the source for an exhaustive understanding. Or
> trial and error.

Super. Changing <nav> in the code to <div role="navigation"> made the
metadata available inside the navbar. This is gas with which I am now
eager to cook.

--m

--
Moacir
moa...@gmail.com