search

Peeragogy / peeragogy-handbook

download free ebook or buy a paper copy
http://metameso.org/~joe/docs/peeragogy-3-0-ebook.pdf
18 stars 12 forks source link

Update how_to_structure.tex #5

Closed martinkoutecky closed 10 years ago

martinkoutecky commented 10 years ago

Fix typo "youwn own" -> "your own" (Is this the preferred way to fix typos? I'm reading through the book and would like to help this way.)

FTG-003 commented 10 years ago

Thanks al-Quaknaa... Pull request can be merged only by @holtzermann17 at the moment. Minor adjustments are very important in a big project :-)

holtzermann17 commented 10 years ago

Thanks @al-Quaknaa and I'm sorry it took me so long to notice this. Yes, changes can be sent this way and it's appreciated!

martinkoutecky commented 9 years ago

Hello guys, what is the status right now? Is this still the preferred way to submit changes? I'm asking because it seems like you must have at least two places where text is modified (TeX & Web), or you have just one and the other is derived from it, or you have some other format that all the others are derived from ... ? How does it work and what is "the master"? Thanks!

holtzermann17 commented 9 years ago

Hi @al-Quaknaa - the Github is currently "ahead" of the web version, but for now the web version is supposed to be the master -- so it's in a slightly inconsistent state at the moment. We'd like to move to a more rational development model. People have not been updating the website recently. On the other hand, I think writing in LaTeX might really limit participation - people would probably like to contribute using Markdown or a visual editor.

I think we need to resolve these matters and now is a good time to do so. We're within days of launching version 3 of the book, and I think we should take a breath and put together a rational development model for v4. Let's discuss ideas here and/or in the Peeragogy in Action Google+ community.

martinkoutecky commented 9 years ago

Hi @holtzermann17 - OK, good to have an update.

My two cents: I was quite happy using reStructuredText for general purpose writing (reports, ...) and very specific purposes (master thesis containing a lot of math and other custom formatting). It was not hard to set up an environment where I wrote rST and had it automatically output an HTML file and LaTeX file (further compiled to PDF).

This is 2 years ago; I can see Markdown kind of won this battle and became the de facto standard markup language; but I don't know it's extension capabilities (the way I know rST) to be able to say how easy it would be to replicate my workflow with MD. Do you know MD well, @holtzermann17 ?

A lot can be done using pandoc (converting from anything to anything); maybe one could let people write in MD, then convert to rST and use that as a master. I can't say if it'd be worth it.

holtzermann17 commented 9 years ago

The current workflow is "supposed to be": people edit on Wordpress using the graphical editor, HTML from Wordpress gets converted to LaTeX by pandoc offline, and then we press print. But in practice, a lot of hand-tuning of the LaTeX has to be done -- images don't get mapped over very nicely, some spacing tweaks and so forth need to be done. And it is then hard or impossible to port many of these changes back to the HTML, so it has to be redone. At first I tried to maintain a set of patches, but that didn't work out well.

Markdown or reStructuredText would help make the 'upstream' source code rational. Actually, Markdown is pretty nice, and it works well on Github. There's an all.md that gives some impression of what the book looks like formatted that way, although that' s a somewhat older version - and it hasn't had energy put into making it look as nice as possible.

All of these formats have something to offer but none of them will solve the "community" question - getting hands-on-the-keyboard editing happening. Moving development to Github for example would create a bit of an obstacle for people who have never used Git before. But maybe it's worth making the move anyway. People would probably figure it out.

martinkoutecky commented 9 years ago

I don't see markdown well prepared to output to many formats. rST has been made for it from the scratch, so in the worst case you can even have raw blocks for the various output formats, while keeping common what formats well automatically (which is most things.)

Couldn't some semi-WYSIWYG editor (e.g. like rsted) be incorporated as the graphical editor of the site and adjusted such that it could hide more advanced features, such that people wouldn't need to a) move to github, b) learn too much? Then people at github would see the raw source and could edit it including things like I've mentioned (raw blocks for html/epub/latex/...) or focus on developing custom directives (like I did for my thesis, to bring AMS math elements into rST).

I'm not trying to make a precise proposal, just get a sense of what direction you/the community wants to go.