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.

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

Markdown (md) to rst reStructuredText conversion : bad list formatting #143

Closed
vvasuki opened this issue Aug 2, 2017 · 5 comments

Comments

Projects
None yet
2 participants
@vvasuki
Copy link

commented Aug 2, 2017

sublists flattened when 2 space indentation is used

Sample code:

md_str = """
# Introduction
This module defines:

- **schema**
  - shared standard schema for communicating and storing Sanskrit data of various types.
  - various idiosyncratic notations used by various modules which deviate from the proposed standards.
- **python classes** (corresponding to the schema) and **shared libraries** for validating, (de-)serializing and storing sanskrit data of various types.
- a **common database interface** for accessing various databases (so that a downstream app can switch to a different database with a single line change).
"""
output = pypandoc.convert_text(md_str, "rst", format="md")
print output

Result:

Introduction
============

This module defines:

-  **schema**
-  shared standard schema for communicating and storing Sanskrit data of
   various types.
-  various idiosyncratic notations used by various modules which deviate
   from the proposed standards.
-  **python classes** (corresponding to the schema) and **shared
   libraries** for validating, (de-)serializing and storing sanskrit
   data of various types.
-  a **common database interface** for accessing various databases (so
   that a downstream app can switch to a different database with a
   single line change).

Newline wrongly required before beginning of list

md_str = """
While designing the JSON **data-model**:
- Type-hint in JSON should be jsonClass (a language-independent name we've picked).
- Try to avoid field-names which conflict with programming language keywords. (Eg. Prefer "source_type" to "type").
- In general, use camelCase or underscore_case for field names - both are fine. Where romanized (potentially mixed case) sanskrit words are used, the latter is the superior convention.
- Where field names and values are to be automatically rendered into various scripts, as in case of sanskrit vyAkarana jargon (eg: vibhakti, lakAra), we prefer SLP1 transliteration ("viBakti", "lakAra").
    - PS: Convenient transliteration modules are available in various languages: please see them listed [here](https://github.com/sanskrit-coders/indic-transliteration#libraries-in-other-languages).
    - A [transliteration map](https://docs.google.com/spreadsheets/d/1o2vysXaXfNkFxCO-WD77C4AEbXcAcJmDVgUb-E0mYbg/edit#gid=0) for reference.
- When in doubt, keep fields optional.
"""
output = pypandoc.convert_text(md_str, "rst", format="md")
print output

Result:

While designing the JSON **data-model**: - Type-hint in JSON should be
jsonClass (a language-independent name we've picked). - Try to avoid
field-names which conflict with programming language keywords. (Eg.
Prefer "source\_type" to "type"). - In general, use camelCase or
underscore\_case for field names - both are fine. Where romanized
(potentially mixed case) sanskrit words are used, the latter is the
superior convention. - Where field names and values are to be
automatically rendered into various scripts, as in case of sanskrit
vyAkarana jargon (eg: vibhakti, lakAra), we prefer SLP1 transliteration
("viBakti", "lakAra"). - PS: Convenient transliteration modules are
available in various languages: please see them listed
`here <https://github.com/sanskrit-coders/indic-transliteration#libraries-in-other-languages>`__.
- A `transliteration
map <https://docs.google.com/spreadsheets/d/1o2vysXaXfNkFxCO-WD77C4AEbXcAcJmDVgUb-E0mYbg/edit#gid=0>`__
for reference. - When in doubt, keep fields optional.

Severity

This is a particularly significant bug because pypandoc is a popular way of converting md files into rst while publishing to pip. For example, this well formatted md file results in very badly formatted pip documentation.

@vvasuki vvasuki changed the title Markdown (md) to rst conversion : sublists flattened. Markdown (md) to rst conversion : sublists flattened when 2 space indentation is used. Aug 2, 2017

@vvasuki vvasuki changed the title Markdown (md) to rst conversion : sublists flattened when 2 space indentation is used. Markdown (md) to rst reStructuredText conversion : sublists flattened when 2 space indentation is used. Aug 2, 2017

@vvasuki vvasuki changed the title Markdown (md) to rst reStructuredText conversion : sublists flattened when 2 space indentation is used. Markdown (md) to rst reStructuredText conversion : bad list formatting Aug 2, 2017

@jankatins

This comment has been minimized.

Copy link
Collaborator

commented Aug 2, 2017

AS we basically only take what pandoc offers, my guess is that this is an issue with pandoc itself. This looks like an issue which might fit: jgm/pandoc#200 Can you have a look if it's that?

@vvasuki

This comment has been minimized.

Copy link
Author

commented Aug 2, 2017

Ah, jgm/pandoc#3511 seems like the right place to pursue a solution, thanks!

@vvasuki

This comment has been minimized.

Copy link
Author

commented Aug 9, 2017

Hi @janschulz . Does jgm/pandoc#3511 (comment) help fix the issue on your end?

@vvasuki vvasuki reopened this Aug 9, 2017

@jankatins

This comment has been minimized.

Copy link
Collaborator

commented Aug 9, 2017

I would like to not switch to a different default. You should be able to convert stuff by using the format, e.g. 'markdown+lists_without_preceding_blankline' instead of plain 'markdown'.

output = pypandoc.convert_text(md_str, "rst", format="markdown+lists_without_preceding_blankline")
@vvasuki

This comment has been minimized.

Copy link
Author

commented Aug 9, 2017

Ah - I'd not seen the format argument. I suppose markdown_github will do the right things. That's reasonable - thanks!

@vvasuki vvasuki closed this Aug 9, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.