Draft: Convert PDF/ Word/ TeX Documentation to Markdown for online documentation.

[moschmdt]

This is still WIP - only to prevent duplicate work in case someone else is already working on it.

The structure was proposed by @garfieldnate.

Related to #9.

[garfieldnate]

Wow, this is a ton of work. I'm surprised to see you've worked on the manual, the tutorials, and the website! Could you note here what parts are not done?

We will need to add conversion to PDF with pandoc for the Soar distribution as well.

[moschmdt]

So here is a list what is still missing/ needs to be improved:

All files

• Image references are not supported out of the box in Markdown - at least to my knowledge - and need to be handled with a pandoc filter or something alike. Since the Markdown should be used in HTML and PDF a compatible solution is required which works for both export formats.

Tutorials

The tutorials were just parsed with pandoc, thus they all require work until completed.

• Rename images?
• Insert code blocks
• Check formatting
• Image extraction via pandoc did work for shapes added on top of images in Word. If there were annotations in Word, the image must be replaced by a new image, e.g., a screenshot.

Manual

Chapter one, two and three are completed.

• Chapter 4
• Chapter 5
• Chapter 6
• Chapter 7
• Chapter 8
• Chapter 9

Homepage

It depends what should remain on the website and what should be moved to documentation. I assume the following stuff is documentation related and could be considered for moving:

• Knowledge-Base/Documentation
  • Command-Line Options for the Java Debugger and CLI
  • Visual Soar Key Bindings
  • Command Line Help
• Knowledge-Base/Building Soar: I think this should be considered developer documentation, thus moved to the wiki pages?
• Knowledge-Base/FAQs and Guides
  • Soar Technical FAQ
  • Soar Design Dogma
  • Soar FAQ (old)
  • Intro to the Soar Debugger
• Knowledge-Base/Technical Documentation
  • All articles

[moschmdt]

I did some work on it in the recent days (commits for this PR will follow). I just pushed it temporarily to gh-pages to check how it will work:

https://moschmdt.github.io/Release-Support/

After this weekend I will not have any time working on that for a couple of months. What is necessary to close this PR for now @garfieldnate?

[garfieldnate]

This is very cool :D

The remaining TODOs I notice at the moment are:

1. Tutorial images
2. PDF builds for tutorials and manual (yes, in addition to the HTML builds from mkdocs)
3. Various smaller fixes; for example, I see an unlinked URL in the "What is Soar?" section. I've also done a bit of work on the manual and tutorials in the last few weeks, so I'll need to port the changes over.
4. I'm uncertain about the tutorials. You went through the trouble of converting them to markdown, which is great, but they are still missing their images. I think we may want to leave the source files for these in DOCX format, as it is likely to be preferred by their main author (John Laird).

I don't think I'm going to be able to accept the PR directly here, because it's too big of a change to review completely all at once, and it is likely going to be a while before all of the little issues are ironed out; meanwhile, the documentation won't be publishable. I would find it much more workable if we migrated one piece at a time to completion, meaning that it was all publishable and we didn't need to keep a copy of the previous source around anymore.

To make this easier, I've created a new repo for gathering all of the documentation to be served in one place here: https://github.com/SoarGroup/Documentation. Could you send a PR to that instead? Then we can publish the initial version, at least. We'll need to add a warning banner at the top saying something like "Under construction - please see official sources at ....". Then we can evolve it from there!

[moschmdt]

I cannot fork the documentation repo when it is empty. Can you please add anything to the repo?

[garfieldnate]

I never knew that! I'll fix it right now.

[moschmdt]

I will close this PR since this is continued in SoarGroup/documentation and the following PRs:

• Initial commit Soar manual SoarGroup.github.io#3
• Add updated version of PR CI pipeline SoarGroup.github.io#4
• Add some homepage articles SoarGroup.github.io#5