org-mode README file formats
Hi, I was building a package where I had a README.org file, which setuptools couldn't find. It listed .md as a valid format, so I was wondering if org-mode was sufficiently plain text to be added to the list of accepted README file formats? For what it's worth, github-markup can handle .org files https://github.com/github/markup Diane
On Mon, 7 May 2018 at 16:54 Diane Trout <diane@ghic.org> wrote:
Hi,
I was building a package where I had a README.org file, which setuptools couldn't find.
It listed .md as a valid format, so I was wondering if org-mode was sufficiently plain text to be added to the list of accepted README file formats?
What's org-mode? Sounds like an Emacs thing based on what I have heard Emacs people say. :) If it is an Emacs thing then I would vote "no" since that's very editor-specific and I suspect trying to support every plaintext file format is never-ending. -Brett
For what it's worth, github-markup can handle .org files https://github.com/github/markup
Diane -- Distutils-SIG mailing list distutils-sig@python.org https://mail.python.org/mm3/mailman3/lists/distutils-sig.python.org/ Message archived at https://mail.python.org/mm3/archives/list/distutils-sig@python.org/message/7...
On Tue, 2018-05-08 at 16:44 +0000, Brett Cannon wrote:
On Mon, 7 May 2018 at 16:54 Diane Trout <diane@ghic.org> wrote:
Hi,
I was building a package where I had a README.org file, which
setuptools couldn't find.
It listed .md as a valid format, so I was wondering if org-mode was
sufficiently plain text to be added to the list of accepted README file
formats?
What's org-mode? Sounds like an Emacs thing based on what I have heard Emacs people say. :)
If it is an Emacs thing then I would vote "no" since that's very editor-specific and I suspect trying to support every plaintext file format is never-ending.
Well yes, it's certainly most powerful, flexible, and feature complete with emacs, but there is work on org-mode support in vim and sublime. Additionally org-mode syntax is supported by GitHub, GitLab, and pandoc. https://en.wikipedia.org/wiki/Org-mode#Integration There's also an argument that org-mode is a good lightweight markup language in and of itself. http://karl-voit.at/2017/09/23/orgmode-as-markup-only/ Since it is breaking out of its source community I thought it at least worth asking about. Out of curiosity, do you have a feeling for how popular a lightweight markup language needs to be before it gets added to the list of setuptools recognized formats? Thanks, Diane
On Tue, 8 May 2018 at 11:00 Diane Trout <diane@ghic.org> wrote:
On Tue, 2018-05-08 at 16:44 +0000, Brett Cannon wrote:
On Mon, 7 May 2018 at 16:54 Diane Trout <diane@ghic.org> wrote:
Hi,
I was building a package where I had a README.org file, which setuptools couldn't find.
It listed .md as a valid format, so I was wondering if org-mode was sufficiently plain text to be added to the list of accepted README file formats?
What's org-mode? Sounds like an Emacs thing based on what I have heard Emacs people say. :)
If it is an Emacs thing then I would vote "no" since that's very editor-specific and I suspect trying to support every plaintext file format is never-ending.
Well yes, it's certainly most powerful, flexible, and feature complete with emacs, but there is work on org-mode support in vim and sublime. Additionally org-mode syntax is supported by GitHub, GitLab, and pandoc. <https://en.wikipedia.org/wiki/Org-mode#Integration> https://en.wikipedia.org/wiki/Org-mode#Integration
There's also an argument that org-mode is a good lightweight markup language in and of itself. http://karl-voit.at/2017/09/23/orgmode-as-markup-only/
Since it is breaking out of its source community I thought it at least worth asking about. Out of curiosity, do you have a feeling for how popular a lightweight markup language needs to be before it gets added to the list of setuptools recognized formats?
When you can say "has broken out" instead of "is breaking out". ;) Basically if the majority of people at a Python conference won't know the format then the burden on the volunteers to support it isn't probably worth it IMO. But since I'm not maintaining Warehouse it isn't my call, just my opinion.
If warehouse punted to a tool like pandoc already, I would see no problem with adding support for everything that pandoc supported (can you imagine – reademe.docx?), but just skimming the requirements file, they are pulling in docutils and mistune, which means they have written warehouse to support rst and markdown, and it is not non-trivial (or less non-trivial) to support other markup languages. Markdown won in the wider world. Supporting that is obvious. RestructuredText has inertia in the python community. Supporting that is obvious. Org-mode? Asciidoc? Txt2tags? Textile? Mediawiki? BB Code? Where do you draw the line? I think the two languages the tooling currently support are sufficient for now. From: Brett Cannon <brett@python.org> Sent: Tuesday, May 8, 2018 2:04 PM To: Diane Trout <diane@ghic.org> Cc: distutils-sig@python.org Subject: [Distutils] Re: org-mode README file formats On Tue, 8 May 2018 at 11:00 Diane Trout <diane@ghic.org <mailto:diane@ghic.org> > wrote: On Tue, 2018-05-08 at 16:44 +0000, Brett Cannon wrote: On Mon, 7 May 2018 at 16:54 Diane Trout <diane@ghic.org <mailto:diane@ghic.org> > wrote: Hi, I was building a package where I had a README.org file, which setuptools couldn't find. It listed .md as a valid format, so I was wondering if org-mode was sufficiently plain text to be added to the list of accepted README file formats? What's org-mode? Sounds like an Emacs thing based on what I have heard Emacs people say. :) If it is an Emacs thing then I would vote "no" since that's very editor-specific and I suspect trying to support every plaintext file format is never-ending. Well yes, it's certainly most powerful, flexible, and feature complete with emacs, but there is work on org-mode support in vim and sublime. Additionally org-mode syntax is supported by GitHub, GitLab, and pandoc. https://en.wikipedia.org/wiki/Org-mode#Integration There's also an argument that org-mode is a good lightweight markup language in and of itself. http://karl-voit.at/2017/09/23/orgmode-as-markup-only/ Since it is breaking out of its source community I thought it at least worth asking about. Out of curiosity, do you have a feeling for how popular a lightweight markup language needs to be before it gets added to the list of setuptools recognized formats? When you can say "has broken out" instead of "is breaking out". ;) Basically if the majority of people at a Python conference won't know the format then the burden on the volunteers to support it isn't probably worth it IMO. But since I'm not maintaining Warehouse it isn't my call, just my opinion.
On 8 May 2018 at 15:00, Diane Trout <diane@ghic.org> wrote:
On Tue, 2018-05-08 at 16:44 +0000, Brett Cannon wrote:
On Mon, 7 May 2018 at 16:54 Diane Trout <diane@ghic.org> wrote:
Hi,
I was building a package where I had a README.org file, which setuptools couldn't find.
It listed .md as a valid format, so I was wondering if org-mode was sufficiently plain text to be added to the list of accepted README file formats?
What's org-mode? Sounds like an Emacs thing based on what I have heard Emacs people say. :)
If it is an Emacs thing then I would vote "no" since that's very editor-specific and I suspect trying to support every plaintext file format is never-ending.
Well yes, it's certainly most powerful, flexible, and feature complete with emacs, but there is work on org-mode support in vim and sublime. Additionally org-mode syntax is supported by GitHub, GitLab, and pandoc. <https://en.wikipedia.org/wiki/Org-mode#Integration> https://en.wikipedia.org/wiki/Org-mode#Integration
There's also an argument that org-mode is a good lightweight markup language in and of itself. http://karl-voit.at/2017/09/23/orgmode-as-markup-only/ [...]
Maybe you can use pandoc as a `setup_depends` and convert it to an acceptable format at build time?
On Tue, 2018-05-08 at 19:32 -0300, Leonardo Rochael Almeida wrote:
Maybe you can use pandoc as a `setup_depends` and convert it to an acceptable format at build time?
I had been wondering how the readme's get used by setuptools. Does the warehouse actually read the readme file directly? or does it preferentially look at long_description metadata? Because if its just using long_description that seems like an obvious place to convert one's random unsupported format.
On Wed, May 9, 2018, at 7:22 PM, Diane Trout wrote:
Does the warehouse actually read the readme file directly? or does it preferentially look at long_description metadata? I think it only looks at the long_description metadata; as far as I know README is just another file in the archive. If you do want to convert it, though, please make sure it can fail gracefully if pandoc isn't there, because it would be frustrating to have problems installing a package from source just because it couldn't convert the README format.
Pypa/readme is what Warehouse uses to render rst and markdown long_descriptions to safe HTML. https://github.com/pypa/readme_renderer There are a number of org-mode implementations; even for a few for Vim and Sublime. https://en.m.wikipedia.org/wiki/Org-mode#Integration ``conda install pandoc`` is the quickest way to install pandoc, AFAIU. The last time I installed pandoc with os packages it pulled in a bunch of Haskell packages. Python-only is the status quo for pypa/readme. On Wednesday, May 9, 2018, Thomas Kluyver <thomas@kluyver.me.uk> wrote:
On Wed, May 9, 2018, at 7:22 PM, Diane Trout wrote:
Does the warehouse actually read the readme file directly? or does it preferentially look at long_description metadata?
I think it only looks at the long_description metadata; as far as I know README is just another file in the archive.
If you do want to convert it, though, please make sure it can fail gracefully if pandoc isn't there, because it would be frustrating to have problems installing a package from source just because it couldn't convert the README format.
If it is an Emacs thing then I would vote "no" since that's very editor- specific and I suspect trying to support every plaintext file format is never-ending. Currently the metadata spec defines the permitted mimetypes. Maybe we should make this more open ended, and leave the set of useful values up to what projects (primarily PyPI) choose to implement? The specification could still say that any format should be a) UTF-8 text - so no README.pdf or README.doc, and b) sufficiently 'plain' that it's readable if tools display it unrendered. The second condition is a bit vague - I might find something readable that you don't - but it's meant to exclude things like HTML and Latex. I don't see any big advantage in specifying a list of allowed content types. Even with the list we have, tools can't rely on any features of
On Tue, May 8, 2018, at 5:44 PM, Brett Cannon wrote: the content except that it's UTF-8. The only real difference is whether people who want to use something else file an issue on Warehouse or start a thread here. :-) Thomas
participants (6)
-
Alex Walters -
Brett Cannon -
Diane Trout -
Leonardo Rochael Almeida -
Thomas Kluyver -
Wes Turner