Skip to content
This repository has been archived by the owner on Sep 17, 2022. It is now read-only.

beginner questions #18

Open
hendrikboom3 opened this issue Nov 4, 2019 · 19 comments
Open

beginner questions #18

hendrikboom3 opened this issue Nov 4, 2019 · 19 comments

Comments

@hendrikboom3
Copy link

hendrikboom3 commented Nov 4, 2019 •
edited
Loading

(1) It looks as if document structure and design is pretty much a do-it-yourself thing with pollen. But I suspect there are a number of pre-built lozenge commands that are available, whether as part of the pollen distribution or some kind of community folklore. Is there a list of these?

(2) One feature I need is file inclusion. Ideally something like ◊include["filename"] to include another file as if its contents were present in the place of the lozenge command. I've tinkered with scribble and not succeeded. In particular I've been unable to get all its at-commands (succh as @(require ...) working reliably from included text. More seems to be involved there than merely calling elem to to necessary conversions after the at-reader has done its work.
I hope it's simpler in pollen.

(I would not mind a restriction that the syntax be properly nested. I have no need to match an open bracket in one file with a close bracket in another, and would appreciate an error message if I seem to be trying that!)

(3) Not as essential, but would be nice: using the markdown parser on part of a document. Something like:
ordinary pollen stuff
◊markdown{ a page or two of markdown-style bullet-point notation }
more ordinary pollen stuff.

(4) Is there a way to indicate that the output file should be somewhere other than in its default location; e.g., in another directory?
-- hendrik
@mbutterick
Copy link
Owner

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 😉

@otherjoel
Copy link

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."))

@hendrikboom3
Copy link
Author

hendrikboom3 commented Nov 5, 2019 •
edited
Loading

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.

@otherjoel
Copy link

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.

@otherjoel
Copy link

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.

@hendrikboom3
Copy link
Author

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.

@hendrikboom3
Copy link
Author

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?

@otherjoel
Copy link

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.

@otherjoel
Copy link

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.

@hendrikboom3
Copy link
Author

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?

@mbutterick
Copy link
Owner 

#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")

@hendrikboom3
Copy link
Author

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))))

@sorawee
Copy link

sorawee commented Nov 8, 2019 via email

@sorawee
Copy link

sorawee commented Nov 8, 2019 via email

@hendrikboom3
Copy link
Author

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.

@otherjoel
Copy link

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.

@mbutterick
Copy link
Owner

mbutterick commented Nov 8, 2019 •
edited
Loading

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.

@hendrikboom3
Copy link
Author

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.

@hendrikboom3
Copy link
Author

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.

@mbutterick mbutterick mentioned this issue Nov 22, 2019
Open
@otherjoel otherjoel mentioned this issue Jan 1, 2020
Closed
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@mbutterick @otherjoel @sorawee @hendrikboom3