search

oeed / CraftOS-Standards

Community standard file formats, communication systems, etc. for ComputerCraft and CraftOS 2.0
Other
20 stars 16 forks source link

Allowing PDFs #32

Closed ardera closed 8 years ago

ardera commented 8 years ago

Markdown is good for small & easy RFCs/COS', but it isn't so good for normal to large-sized Specifications. For me, it was not possible to create a 3-level Index without using HTML. It's not possible to include images without using HTML (I think), and when you use HTML, you have to upload them somewhere first. Markdown's Sans-Serif font family is good for small texts, but it gets really hard to read large texts in Sans-Serif (Actually, that's what the Serif font family is for)

I'm currently writing the UCGv3 file format specification, and I think with using pdf, you would help both the writer and the reader.

Things possible in PDF are possible in Markdown too using HTML tags, but you don't have to code in Assembly when you could use C++ too, do you?

ardera commented 8 years ago

still, you have to upload them somewhere first. It's not a compact way of including schemes

viluon commented 8 years ago

Agreed with @demhydraz, especially since this is GitHub flavoured. What does @oeed think?

oeed commented 8 years ago

I get that PDFs have a small edge over Markdown; although, your RFC might actually be better in Markdown as, rather than having all your code as screenshots, you can actually embed it.

I understand what you're saying about serif fonts (although I've never been a fan of the LaTeX font to be honest). The benefits are debatable anyway. It also forces you to be more concise and avoiding large paragraphs.

But the bigger issues have to do with GitHub integration. The single biggest issue is that people can't really edit the PDF, that's half the point of them. Even if you included the LaTeX code for it many people wouldn't know how to edit it anyway. If we need to change something in the document or add something that's missing we can't.

If you do make changes an upload them it doesn't show what's changed either. We also loose a consistent style which makes the documents easier to read and find what you're looking for.

I know it sucks, but I just don't think the benefits outweigh the negatives.

ardera commented 8 years ago

Yeah okay.. You're right oeed