beginner questions about pollen-users HOT 19 OPEN

Here’s a working example for your second question. Every Pollen document provides two values, a doc and a metas, which you can fetch with get-doc and get-metas.

So we can write an include tag/function that gets the doc from another file. This will be an X-expression that starts with '(root ...), so I used cdr, unquote-splicing and the @ splicing function to lift its elements into the surrounding X-expression (in the "calling" doc).

pollen.rkt:

#lang racket/base

(require pollen/core pollen/decode)

(provide root include)

(define (root . elems)
  `(body ,@(decode-paragraphs elems #:force? #t)))

(define (include file)
  `(@ ,@(cdr (get-doc file))))

other-file.html.pm:

#lang pollen

◊h1{My Included File}

It feels ◊strong{good} to be included.

index.html.pm

#lang pollen

◊h1{Main File}

I'm not complete on my own...

◊include["other-file.html.pm"]

Saving all of these in the same folder and "running" index.html.pm in DrRacket results in:

'(body
  (h1 "Main File")
  (p "I'm not complete on my own...")
  (h1 "My Included File")
  (p "It feels " (strong "good") " to be included."))

from pollen-users.

History has taught me that it’s difficult to answer these questions in the abstract. It would be better for you to post a concrete example of something that doesn’t work the way you expect.

Mostly, Pollen is a more convenient way of writing Racket programs that process a lot of text, using X-expressions as the medium of exchange. Some people like it better than Scribble; some people don’t 😉

from pollen-users.

Thanks for the working example. It works. And seems a lot simpler than anything similar I've found in Scribble. And it puts the included text exactly where I include it. The closest thing in Scribble creates a formal subsection and moves it to the end, which is one thing I do not need or want.

It does seem to demand that I place a #lang pollen at the start of the included file.

I had to make one change: if the stuff from the included file ends up being just one string, and not a list, the cdr fails; instead I have to wrap to make the cdr succeed. I'm guessing that in this case it leaves out the call to root? Is this a bug or a feature?

Hmmm. Why would it do that? I'll have to try an included file with some losenges in it do see if it's any different.

from pollen-users.

I had to make one change: if the stuff from the included file ends up being just one string, and not a list, the cdr fails; instead I have to wrap to make the cdr succeed. I'm guessing that in this case it leaves out the call to root? Is this a bug or a feature?

Lots of missing information here. As Matthew said earlier, the best way for us to help is if you can provide a concrete example of something that does not work they way you expect.

Another thing I always recommend to people: work through the [four tutorials][1] in the Pollen docs — actually type out and run the examples in DrRacket. Even if you think you can understand the concepts just by reading.

from pollen-users.

Regarding your 4th question in your original post, you may be interested to read this discussion on the old Google groups list.

The approach would be to use the markdown package to parse the markdown inside a tag function, and then optionally re-run the resulting x-expression through the existing tag functions.

from pollen-users.

So pollen uses the Racket module mechanism to include files, and so they have to be Racket modules. Does that mean that it's possible to include a Scribble module into a Pollen file? I suspect not; I suspect there will be incompatibilities.

from pollen-users.

Regarding the fourth question. The markdown package you refer me to describes a function parse-markdown. But it takes a path or a string as argument, but doesn't a lozenge-function instead receive a list of x-expressions?

from pollen-users.

Does that mean that it's possible to include a Scribble module into a Pollen file? I suspect not; I suspect there will be incompatibilities.

Per the docs:

The Pollen rendering system relies on these two exported identifiers [doc and metas], but otherwise doesn’t care how they’re generated. Thus, the code inside your Pollen source file could be written in #lang racket or #lang whatever. As long as you provide those two identifiers and follow Pollen’s file-naming conventions, your source file will be renderable.

So if a Scribble module can be made to do (provide doc metas) with doc being an x-expression and metas being a hash table, then it can be treated like any other source within a Pollen project. But just like any other Pollen source, you'll have to write code to handle the x-expression you receive and transform it into your target format.

from pollen-users.

But it takes a path or a string as argument, but doesn't a lozenge-function instead receive a list of x-expressions?

There is no such thing as a lozenge-function. The lozenge is just how you signal to Pollen that what follows should be interpreted as Racket code instead of as literal text.

Further, a string is a valid x-expression.

from pollen-users.

Regarding the fourth question. The markdown package you refer me to describes a function parse-markdown. But it takes a path or a string as argument, but doesn't a lozenge-function instead receive a list of x-expressions?

from pollen-users.

#lang pollen/markup

◊(require markdown racket/string)
◊(define (md . strs)
  (cons '@ (parse-markdown (string-join strs ""))))

Before the markdown block.

◊md{**hello**

there!

_world_}

After the markdown block.

Result:

'(root
  "Before the markdown block."
  "\n"
  "\n"
  (p () (strong () "hello"))
  (p () "there!")
  (p () (em () "world"))
  "\n"
  "\n"
  "After the markdown block."
  "\n")

from pollen-users.

About the include function you provided. It seems to require that the returned doc value be a pair.
But sometimes it isn't. Is this a bug or a feature? And if a bug, is it a bug in pollen or a bug in include?

Here's the case I'm having trouble with. The included file, wiko.mt3, is truly trivial:

#lang pollen
xx yyy

I get the error message

hendrik@midwinter:~/write/Melinda.pollen/Melinda/src$ raco pollen render wko.html
pollen: rendering wko.html
pollen: rendering /wko.poly.pm as html
cdr: contract violation
  expected: pair?
  given: "xx yyy"
  context...:
   /home/hendrik/write/Melinda.pollen/Melinda/src/pollen.rkt:10:0: include
   (submod "/home/hendrik/write/Melinda.pollen/Melinda/src/wko.poly.pm" pollen-module): [running body]
   temp37_0
   for-loop
   run-module-instance!125

etc. etc.

The problem seems to be that the value of doc that's returned is just a string, and not root consed onto the beginning of anything. Evidently the running example you provide is too complex to trigger this problem.

For completeness, the including file:

#lang pollen

◊include["wiko.mt3"]

and the pollen.rkt file:

#lang racket/base

(require pollen/core pollen/decode)

(provide root include)

(define (root . elems)
  `(body ,@(decode-paragraphs elems #:force? #t)))

(define (include file)
  `(@ ,@(cdr (get-doc file))))

from pollen-users.

from pollen-users.

from pollen-users.

Yes. renaming the file worked. The naming of files has become a black art.
I thought the #lang line would suffice to tell pollen how to read it. Evidently not.

from pollen-users.

Again, read the docs thoroughly, they are really helpful.

File Formats

There isn’t really defined behavior for what happens when you use random file extensions. If you aren't going to use the default file extensions, you should change the appropriate parameters to reflect your choices.

from pollen-users.

To supplement @otherjoel’s answer: your question about file naming is also addressed in the first tutorial and emphasized with the warning Don’t skip this section! It explains an essential Pollen concept. (It is not the only section so labeled.)

I can guarantee that if you insist on learning Pollen by avoiding these essential concepts, then yes, everything will seem like “black art”, I’m afraid.

from pollen-users.

Yes. renaming the file worked. The naming of files has become a black art.
I thought the #lang line would suffice to tell pollen how to read it. Evidently not.

from pollen-users.

I had read the section about file names, but I did not realize that it applied to the files I included, since the source file were fully identified in the ◊include request and all decisions as to source format and object format has already been made based on the name of the main source and object file. It's not as if I was asking it to make linked output files, each in a different output format.

As for the extensions I was using, they were already there in the files I was trying to convert to pollen.

from pollen-users.