pillar-markup / pillar Goto Github PK

When the support parameter includes (a part of) outputDirectory, Pillar will try to copy (the part of) outputDirectory to itself. We should make sure this does not happen by adding a special case to the code. For example, the following configuration is problematic:

{
  "support" : [ "**/figures" ]";
  "outputDirectory" : "result";
}

because the result/ directory might include a figures/ sub-directory: this will indeed happen when pillar is launched twice without removing the result/ folder.

• The method assertWriting:includesTexts: tests that the elements of the second parameter all appear in the generated text. We would like to increase the strength of this method by making sure that elements appear in the same order as specified in the text. This method must be reimplemented and some tests will probably have to be fixed.
• similarly tests such as PRAsciiDocWriterTest>>testHeader and PRPillarWriterTest>>testHeader pass even if the writer writes more headings marks. For example, if the Pillar writer writes !!! Foo instead of ! Foo, #testHeader still passes because it only checks for substrings (! Foo is included in !!! Foo). Using regular expressions might help.

Into the outputFile parameter we could add the possibility to write {date} (the current date), {ext} (the extension)… For example,

{
  "outputFile": "output_{date}.{ext}";
}

LaTeX is very useful to write mathematical formulas for example. It would be nice to be able to embed LaTeX formulas inside a Pillar document and get these formulas fully exported. Org mode does something similar already.

We could trim some things during the parse.
For example anchors or parameters.

We should be able to write

${ slide : Title | label = foo }$ 

as

${slide:Title|label=foo}$

We need a script to create a release with tarballs

We could add some progress sentence into the stdout (for the beginning of the parse etc…)

In particular the links with an alias. In that case show an external link in footnote or in parenthesis. (\footnote{\ur{address}})

Currently, figure width can only be specified in terms of percentage of the page width. Sometimes, it is interesting to have a deeper control by specifying for example a number of pixels or points.

Some configuration parameter are inherited from the configuration's parent (that's the case of most parameter) whereas some parameters are not inherited (that's the case of configurations for example). There should be a way to have a tell in the parameter's magritte description that it "should inherit" or not.

On windows Pillar should generate a .bat and not a .sh

It would be nice to simplify the creation of links to standard websites such as Wikipedia and Youtube. For example, +youtube:iJZYG5qwHHI+ would represent a particular video on Youtube and *wikipedia:SOLID_(object-oriented_design)* would be a link to a Wikipedia article on the SOLID principles. Beyond Youtube and Wikipedia, we could have links to Amazon, Google, Smalltalkhub, Github... Some links could be parametrized: for example, +youtube:iJZYG5qwHHI|controls=0|showInfo=0+ would be the same as +youtube:iJZYG5qwHHI+ without the player controls and video title.

(requires #19)
Often I want to link someone to a specific section/chapter of a document.
For example in Sphinx documentation http://sphinx-doc.org/tutorial.html#autodoc each section has an id and when you hover the header with mouse there is a ¶ symbol I can click on.

We could for example choose the delimiter character.

In Pillar, a code block can be written in a way that Pillar will execute it and render its result instead of just printing the block's code. This is a powerful but unsecured feature. It would be good to secure it by having a controlled interpretation and forbid access to unsafe parts of the image.

Check the content of a slide to adapt the option and not use "fragile" all the time.

Create a syntax to instantiate any object (aka. object literals). This is useful to create structured data and is similar to what Wikipedia's Infobox and STON provide.

Each section title should automatically generate an implicit hyperlink target (aka, anchor) pointing to the section. The text of the hyperlink target (the "reference name") is the same as that of the section title.

Ensure that scripts with a 'language' parameter are properly exported in LaTeX

Since we have a document item for the figures I think we do not need the «embedded» variable anymore. (in PRReference and subclasses)

in HTML and LaTeX.

It could be cool to have the list of the files on the templates to be able, for example, to build menu.
We need

• to have a list of "files" objects available for the templates
• for each of these files, all its properties configured in the file
• also, it would be good to access the name of the output file in a template
  Example

We want to read documentation and books everywhere. This is why Pillar can already generate books in HTML, Markdown and PDF (through LaTeX). More export formats are necessary: for example, EPUB and DocBook. A unit-testing framework will help you make sure your exporter is complete. You can get inspiration by looking at the HTML and LaTeX exporters.

Exporters:

• EPUB
• DocBook

The parser create too much paragraphs and we have to Hack the document model because of that.

Need to finish #4 before.

Related to #7 and #34.

We should stop the parse of a link at the end of the current paragraph. If we do not find a second $* before the end of the paragraph, we act as if we don't have a link.

To facilitate application documentation, it would be nice to write not only code in the documentation, but also the expected output. That way, the documentation is automatically checked at each new application version. The Pillar syntax could be

    [[[test
    3 + 6
       --> 9
    ]]]

In this case, Pillar should evaluate 3+6 and make sure it equals 9. If it doesn't, Pillar can raise a warning.

Need to finish #4 before.

The commented lines should be link to the PRDocument and not into some items as a Header.

Add a footnote annotation on the pillar syntax. http://orgmode.org/manual/External-links.html

# 
## Foo 

and

## Foo

generate the same list, this is bad.

The configurations parameter of any configuration is a dictionary with a name string as key and configuration as value. It means a configuration does not know its name. It would be good to make the configurations a collection with each configuration knowing its name.

I added bad dependencies. This need to be clean (For example the document model should not depend on the exporter core).

Currently the columns are exported in Beamer, DeckJS and HTML only.
We need to finish it on the other exporters.

Implement the capability to have multi-line annotations (and ordered/unordered/definition list items).
Either with open/close syntax, or Markdown style where whitespace after a list item indicates that it's part of the previous line (much like the TODO items in this very list).
Writing large books or bodies of docs under Git-like version control requires hard line breaks (typically around 80 chars), to make it easier to browse diffs (and to avoid horizontal scrolling that results in paragraph-sized single lines).

Into the tables we can do |{! Foo or |!{ Foo. We should only be able to do the first.

To facilitate documenting graphical applications, it would be nice to write, in the application documentation, the code that takes screenshots for the application automatically. Currently, the documentation writers must make the screenshots manually, refer to the picture file in the text, and update all screenshots at each application version. With this project, the documentation will have to be compiled for each new application version and the screenshots will be updated automatically.

It is currently possible to reference sections and figures but not tables. This must be changed.

Check inter-files links to see if the file exist, if not, raise a warning.

Ensure that a figure is at the center in markdown http://clariallende.gitbooks.io/smalluml/

embeded files adds an extra % at the end
tide-framework/marina#4

Fix escaping in https://pharo.fogbugz.com/f/cases/12948

Check if the HTML is valid and adapt Pillar if not.

For now we can't use a special characters on a formated text. We should change that.
Same on a slide's annotation for the title.

It must be possible to specify a table cell containing a text that spans multiple lines.

The parser that takes text in Pillar syntax as input and produces a Pillar document tree as output is hard to understand and modify. It would be nice to refactor or rewrite it. Many unit-tests will guarantee that the new parser has the same behaviour as the old one.

Some annotations are transformed and cannot be export in pillar anymore.
We should not transform the document in some cases. (Pillar export for example).

We want more annotations. For example,

• ${note:some text}$ to have some configurable emphasis on a
  piece of text;

• ${note:value=some text}$ (equivalent to previous one) (the default value= works the same as for
  Java annotations);

• ${index:AClass}$ to add AClass to the document index;

• ${cite:Duca99b}$ to reference a particular item of a bibliography;

• ${cite:value=Duca99b|page=90}$ (equivalent to previous one but
  additionaly specifies a page number;

• ${background:file://foobar.png}$ to specify the background of the
  current section;

• ${annote:some text with a curly brace \} inside}$ (shows how to
  escape a curly brace).

• ${html:div-class=name}$ in HTML add a div with a class).

  The PRAbstractAnnotation represents the infrastructure of this syntax. More subclasses must be created to test the infrastructure.