write a howto for mockDoc

[kohlhase]

You should write a howto (a LaTeX document that tells readers how to do ...) with all the steps it takes to make your first LaTeXML document format. Then the next generation has something to read. And such a howto would be valuable for Bruce to have. The idea is to use your mockDoc class as an example and explain the code and the steps (see the issues here) how to get there.

[angerhang]

I just uploaded a proposal like howTo.tex file. Do you think if there is anything that I should include is missing?

    \chapter{introduction}
    \chapter{Understanding TeX}
    \section{Make Customized TeX file}
    \section{Programming in Macro}
    \chapter{Understanding LaTeXML} 
    \section{Using LaTeXML}
    \section{LaTeXML Binding}
    \subsection{Minimal LaTeXML Structure}
    \subsection{RelaxNG Schema}
    \chapter{References}

[kohlhase]

I guess you can assume that people know LaTeX (there are many good tutorials), so you do not want to write the "understanding TeX chapter. You may want to give the class file just for reference, but not explain it further.

[angerhang]

@kohlhase I just finished proofreading the howTo document draft. Do you think it would be a good idea to meet and discuss the changes for the document?

[kohlhase]

after GenCS?

I have some things I want to meniton

• citations --> biblatex, kwarc.bib
• listings.sty
• do not copy over mocdock stuff, reference it relatively.

[kohlhase]

oh, and you should reorganize the repository remove firsttrial (not much worth there), rename secondTrial to mockDoc ...

[angerhang]

How about tomorrow after GenCS, because I have another class that requires attendance after today's lecture?

[kohlhase]

sure

[angerhang]

@kohlhase what do you think of the updated howTo.

[kohlhase]

much more suitable style, carry on like this. There are a few beautifications I would propose, but they have time.

BTW, this is not a thesis, so you do not mention the supervisor in this. So just make me a co-author (last is the correct place for this).

[angerhang]

@kohlhase should I bring a printout of the document to class tomorrow, so we can discuss the changes need to be made and finalize the howTo document?

[kohlhase]

very good idea.

[angerhang]

@La-Stravaganza has rewritten the howTo doc. I think it will be nice to meet again to proofread it and discuss how to merge SMGlom fork.

[kohlhase]

I am afraid, the document is not quite complete yet.

I have extended the document with an appendix, you should try to write something (and intro sentence) about every file (point out the interesting bits. And they should be referenced above.

Let's make this better.

[kohlhase]

I will work some more on the text of the document. I think the most immediate task on your side is to replace the example with the minimal one you had somewhere earlier and run it.

[kohlhase]

BTW, I am using biblatex.sty for the bibliography, that is much better. One of the advantages is that we can use the @online type, which is better suited for citing web pages. I converted the mockdoc git repos to a citation as well. I like that better than footnotes.

[kohlhase]

general coding style critique: do not use \ (almost ever, certainly not at the end of paragraphs). Another one, in a document like this you do not address the reader by "you will".

[kohlhase]

I ended up restructuring (rethinking the structure) of the document quite radically, so that I am much more happy with it, even though it is a mess of ednotes. You should have a good look (so that you learn academic writing), and then we should discuss.

[kohlhase]

In particular, the ednotes should be discussed.

[angerhang]

I have some questions about a few ednotes and I commented on them respectively. Can you have a look?@kohlhase

[kohlhase]

With the "minimal example", I mean an example that is much much shorter than mockDoc.tex; actually as short as possible. I want to use that in the howto. The "real world" flavor of mockdoc.tex does not give us anything (it only wastes space and the reader's attention).

[kohlhase]

at the top of section 2, you are using latexmlc and `latexmlpostthat is not how it is intended. You can use post from insicelatexmlcby giving the respective options tolatexmlcdirectly (and maybe--post`` you have to try).

[kohlhase]

the stylesheet is still not general enough. What if it has two p at the top of a section, ...

I have brought the stylesheet into the right form; please understand and describe it in the text.

[kohlhase]

but all in all, I think we are nearing a release.

[angerhang]

After experimenting with latexmlc options, I couldn't really get --post to do what we intended, and later I found Generating different formats at the same time, which suggests --post inside latexmlc at least for right now does not work.

[angerhang]

I ended up shrinking mockDoc.tex to a relative small size and its derivatives, it is not the smallest we can get, however it still retains the schema of the original mockDoc.tex and shows off all the desired features. I don't know if we want mockDoc.tex to be any smaller. The good thing is by using the modified mockDoc.tex, we can already reduce the pages from 14 to 10.

[kohlhase]

I like the new mockDoc.tex. I have tweaked the makefile, and the schema (what was generated was not schema-conformant), corrected the xslt (my fault) and the bib file (your fault). Now, the document must be carefully re-read.

[kohlhase]

I will have a look at calling the stylesheet.

[kohlhase]

Now, I see that the explanation (the code snippets there) are no longer up-to-date with the reality.

rather than copy them into the document, you should use the linerange={⟨first1⟩-⟨last1⟩,⟨first2⟩-⟨last2⟩, and so on} feature of the listings package to reference the the desired part. This is more manageable.

[kohlhase]

Also we should not list files in the appendix that have been listed completely before. This saves space.

[angerhang]

Yes I was mistaken on the bib file (my fault). I cleaned up the code snippet style you mentioned and edited the needed parts. I will do more proofreading and handle the last ednote.

[angerhang]

I think the howTo file is close to complete. Shall we arrange a meeting to iterate it through?

[kohlhase]

I went over the document again and added some things (an abstract and toc), .. now it is good to go from my side (unless I forget to push).

Will you announce it to the LaTeXML mailing list?

On 25/03/15 02:24, angerhang wrote:

I think the howTo file is almost completed. Shall we arrange a meeting to iterate it through?

— Reply to this email directly or view it on GitHub https://github.com/angerhang/mockDoc/issues/5#issuecomment-85771108.

---

Prof. Dr. Michael Kohlhase, Office: Research 1, Room 168 Professor of Computer Science Campus Ring 1, Jacobs University Bremen D-28759 Bremen, Germany tel/fax: +49 421 200-3140/-493140 skype: m.kohlhase

m.kohlhase@jacobs-university.de http://kwarc.info/kohlhase

[angerhang]

I think you might have forgot to push, because I didn't see any abstract or toc. I can announce it to LaTeXML after you make the latest push.

[kohlhase]

you are just much faster than I am :-).

[angerhang]

: )