search

rstudio / markdown

The first generation of Markdown rendering for R (born in 2012), based on commonmark. Note that this package is markdown, not *rmarkdown*.
https://cran.r-project.org/package=markdown
Other
85 stars 78 forks source link

Creation of TOC should be a separate option from creating id for headers + documentation #53

Closed jiho closed 10 years ago

jiho commented 10 years ago

The documentation says:

 ‘'toc'’ assigns an HTML id to each header of the form 'toc_
          position of the header within the document (starting at 0).
          The user must create the top level table of contents by hand.

But the TOC is actually automatically created. It would give the user greater control if the creation of id tags and the display of the toc could be separate. For example: having ids allows to create links to specific sections from other pages but displaying the TOC on the page itself is not required, sometimes even not wanted.

yihui commented 10 years ago

Thanks for the report. I have corrected the documentation. As for the request of separating toc from creating id's, you can consider the new rmarkdown package: http://rmarkdown.rstudio.com Pandoc creates id's even when you do not want TOC.

This markdown package is basically in the maintenance mode now. We will not add new features unless you send pull requests.

jiho commented 10 years ago

The problem of course is that rmarkdown is not self-contained (one needs to install pandoc for it to work) so I cannot depend on it in another package and hope that everything will "just work", even when (if?) rmarkdown gets on CRAN. Is there any plan to include pandoc within the package? (I know it's big but it would be so much more convenient).

jjallaire commented 10 years ago

We aren't able to include arbitrary binaries within packages on CRAN. We do however include pandoc within every copy of RStudio (as of the current preview release: http://www.rstudio.com/ide/download/preview) as well as provide instructions on how to use this version of pandoc outside of RStudio (https://github.com/rstudio/rmarkdown/blob/master/PANDOC.md)

On Sun, Apr 13, 2014 at 2:06 PM, Jean-Olivier Irisson < notifications@github.com> wrote:

The problem of course is that rmarkdown is not self-contained (one needs to install pandoc for it to work) so I cannot depend on it in another package and hope that everything will "just work", even when (if?) rmarkdown gets on CRAN. Is there any plan to include pandoc within the package? (I know it's big but it would be so much more convenient).

Reply to this email directly or view it on GitHubhttps://github.com/rstudio/markdown/issues/53#issuecomment-40314548 .

jiho commented 10 years ago

So, as long as people are using RStudio, they should be all set, right? They don't even need to install rmarkdown as far as I understand. That helps in my usage scenario (I can just ask people to use RStudio).

Still for the rmarkdown package itself, that's a pretty big dependency: either install pandoc or install RStudio, both outside of R (i.e. not through install.packages, leading to potentially out of date installs etc.). I understand that just including the executable is not possible but plenty of packages include libraries. Is it not possible to do it with pandoc because it is written in Haskell (as opposed to C or Fortran)?

jjallaire commented 10 years ago

Believe there is nothing I'd like more than to include pandoc directly in the package. Unfortunately Haskell has a giant footprint -- you'd have to build the GHC compiler + the Haskell platform + plus the hundreds of Haskell libraries that pandoc depends on. This is way beyond the size and scope of what can be included in an R package.

On Sun, Apr 13, 2014 at 5:23 PM, Jean-Olivier Irisson < notifications@github.com> wrote:

So, as long as people are using RStudio, they should be all set, right? They don't even need to install rmarkdown as far as I understand. That helps in my usage scenario (I can just ask people to use RStudio).

Still for the rmarkdown package itself, that's a pretty big dependency: either install pandoc or install RStudio, both outside of R (i.e. not through install.packages, leading to potentially out of date installs etc.). I understand that just including the executable is not possible but plenty of packages include libraries. Is it not possible to do it with pandoc because it is written in Haskell (as opposed to C or Fortran)?

Reply to this email directly or view it on GitHubhttps://github.com/rstudio/markdown/issues/53#issuecomment-40320315 .

hadley commented 10 years ago

Another approach would be to ask the the CRAN maintainers to install binary pandoc on windows & mac cran - this might not be too hard, since pandoc is a widely used tool.

jiho commented 10 years ago

This would solve the problem of passing the tests on CRAN etc. and therefore being able to submit the package to CRAN. But it still leaves it to the user to install pandoc on his/her machine for rmarkdown to work right?

hadley commented 10 years ago

Yes, but that's not hard, and it's already taken care of if they're using Rstudio. If we want to use pandoc goodness, users have to have pandoc installed.

jiho commented 10 years ago

FYI, the question arises from my use of the markdown package for a package I am working on: a static site generator in R https://github.com/jiho/yssr It's very primitive at this point (I just wrote what I needed for this site: http://oem.obs-vlfr.fr/). I've written a small README to help you figure things out. For this package, I need a way of turning a (R)markdown file into HTML code, in the most basic way possible (i.e. not adding html or body tags)

hadley commented 10 years ago

@jiho you might also want to have a look at my rsmith project.

jiho commented 10 years ago

@hadley : looks like I am late to the party ;)

I'll look into it. Your work is probably much more polished than mine...

ramnathv commented 10 years ago

There are two other efforts as well.

  1. samatha
  2. poirot
jiho commented 10 years ago

This thread is getting out of context... but interesting! I knew about Poirot and I tried to use it but I must admit I did not really know where to start. A HOWTO + very simple example would help very much. I did not know about samatha, I'll check it out.

One thing I need such a tool to do is to run R scripts which deal with data and generate pages accordingly (and yssr, therefore, does). Before anything else, yssr looks for all R scripts in the source dir and runs them. I use this to read data in csv files and generate pages based on this data. For example, this can be used to generate an address book: from a spreadsheet with all contacts, generate a page for each contact by a_ply'ing on the dataframe and generating a markdown file for each line. One could probably also generate pages for all names starting with a given letter.

This is the kind of stuff that is usually dealt with dynamically, server-side. But if the data does not change very often (and does not change dynamically), it is a bit of a waste of resources. This is akin to "dynamic pages" in Middleman.

In a real world case, I use this to generate these pages: http://oem.obs-vlfr.fr/ues_m1.html http://oem.obs-vlfr.fr/ues_m2.html and all pages linked form there, from a common csv dataset.

How would I go about his with rsmith/samatha/poirot ?

hadley commented 10 years ago

For rsmith, you'd need to write a plugin. The advantage of rsmith is that it has an architecture that is very very easy to extend. The disadvantage is that it doesn't have many plugins yet, and it's not very well documented. But you can read how metalsmith works and then fairly easily port it to R.