Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MEP: MyST Core Design Philosophy #5

Draft
wants to merge 1 commit into
base: chrisjsewell-mep-process-proposal
Choose a base branch
from
Draft

MEP: MyST Core Design Philosophy #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions meps/mep-0002.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
mep:
id: 2
author:
- Chris Sewell @chrisjsewell
created: "2020-10-05"
type: Process
status: Active
discussions-to: https://github.com/executablebooks/myst-eps/discussions/4
---

# MyST Core Design Philosophy

Markedly Structured Text (MyST) is intended to provide:

1. A human readable text format for writing technical and scientific documentation.
2. A specification for an abstract intermediate representation, independent of the input and output formats.
3. A specification for a reference parser implementation, which can be used to convert from the text format to the abstract intermediate representation.
4. A specification for a reference renderer implementation, which can be used to convert from the abstract intermediate representation to a variety of output formats.

## Human Readable Text Format

The MyST text format is intended to be a human readable format, which is easy to write and read, and which can be converted to a variety of output formats.

To borrow from the [Zen of Python](https://www.python.org/dev/peps/pep-0020/):

1. Beautiful is better than ugly.
2. Explicit is better than implicit.
3. Simple is better than complex.
4. Complex is better than complicated.
5. Flat is better than nested.
6. Sparse is better than dense.
7. Readability counts.
8. Special cases aren't special enough to break the rules.
9. Although practicality beats purity.
10. Errors should never pass silently.
11. Unless explicitly silenced.
12. In the face of ambiguity, refuse the temptation to guess.
13. There should be one -- and preferably only one -- obvious way to do it.
14. Now is better than never.
15. Although never is often better than *right* now.
16. If the implementation is hard to explain, it's a bad idea.
17. If the implementation is easy to explain, it may be a good idea.
18. Namespaces are one honking great idea -- let's do more of those!

How does this apply here...

### Why not just CommonMark?

CommonMark is a great specification for a human readable text format, and is the basis for the MyST text format.

However, it is not a specification for an abstract intermediate representation, and it does include all of the features that we would like to support for scientific documentation.