pdf files should be generated based on some marked up format

[coreyreichle]

The current set of pdf's provided as docs do not allow for copy/pasting of text to and from. These docs should be generated based on markup in the git repo, rather than just added to the repo as PDF's.

If text-based source is available, I'm willing to work on the "translation" into marked up documents, and the build scripts to generate various formats.

[dranch]

This isn't entirely true.. both acroread 9.x and evince on Linux copies text just fine. I recommend you get a different PDF viewer. For me personally, the readme.md files can ONLY be viewed on "Markup" based websites which is a show stopper vs. PDFs are truly portable to any platform.

--David

[coreyreichle]

I'm using the default plugin in Chrome, and it's not allowing for copy/paste.

I agree, PDF's are more or less universal. Like I offered, I'd be willing to take the text source, and build docbook or similar markup files, that can then be ran through any number of processors, and generate output in any number of formats. (Docbook2html, for example).

[dranch]

Sounds like a bug in Chrome so as I recommended, try another viewer. I'll leave it to John to comment on this issue but looking at the PDF properties, these various documents are authored in Microsoft Word. I highly doubt there are any Markdown editors that can match Word's function and flexibility. As such, you would have to constantly import his .doc files and export them and ensure the correct formatting, etc. is always maintained. Not a trivial job and would be a never ending task. It's also worth mentioning that good documentation in an open source project is RARE and the wealth of documentation John is creating for various use cases is fantastic. Creating additional overhead for him to create and maintain these documents should be kept to a minimum. Just my $0.02.

--David

[coreyreichle]

I agree. Adding overhead for him is a bad idea. Which is why making the docs a format that is easily updateable, and translatable into multiple formats is a good idea. And, I agree, the wealth of docs is great today.

Yes. I'd be willing to put up, and do a pull request if I have the source docs.

[irl]

From the perspective of Debian, we do ship the original word documents in our packages as Debian policy states that source files must be shipped in their preferred format for editing. PDF files do not count as source code in this case.

I would prefer it if the word documents were also included in the git repository, but I'm not too concerned with continuing to receive these out-of-band for inclusion in the Debian source packages.

We store these files in the Debian patch portion of the source package, separate from the upstream code:

http://sources.debian.net/src/direwolf/1.2-3/debian/
http://sources.debian.net/src/direwolf/1.2-3/debian/README.source/

[coreyreichle]

So, maybe the best option is just adding the docx files to the git repo?

[coreyreichle]

FWIW, I just forked the project, so I can start doing, instead of asking. I'll start first by getting the docx converted (Acceptably) into something like ODT format, which can easily be converted into a pagination form (Such as docbook).

I'll request a merge when I get something worthwhile to merge in :)

[bradanlane]

Having the documentation in an editable format would be beneficial for anyone adding or extending a feature. Otherwise, there is the risk the documentation will be out of sync/date with the software.

[blaisep]

Hi @dranch , I'm pretty handy with Sphinx, so I can get the docs set up on readthedocs.org. This would address all the issues raised in the thread (version control, branching, PDF, copy/paste, etc. @coreyreichle , why don't you add me as contributor to your fork and we can use that as a proof of concept to make David's life easier?
73s
Blaise KK6IHP

ps: you guys need to get out more ;-)
...the docs scene has really taken off. For example, these docs: https://docs.python.org/3/py-modindex.html are compiled from this source: https://github.com/python/docsbuild-scripts

[wb2osz]

Rewriting hundreds of pages of documentation, in some other document format, would be a huge project and not likely to happen anytime soon.