12

We often produce documents that will have to be edited by others who are not as proficient at LaTeX than us, and not as keen to spend time learning. It may be that such documents will persist for a long time after we lose responsibility for them.

What are good practices to make such documents as durable as possible, such that non-experts can continue to productively edit and compile them, and further that there are minimal opportunities for a non-expert to break the document or turn it into messy code (say, by being wildly inconsistent with formatting and structure commands)?

To provide a somewhat concrete example, suppose I am the current editor of an encyclopaedia which is amended very slowly. I have the opportunity to typeset it from scratch in LaTeX, but I would like it to continue to be amended (and beautiful) when new editors, who may arrive with no LaTeX knowledge, tend to it. How should I go about achieving this?

dbmag9
  • 1,411
  • 1
    Seems as if you need to carefully define macros/environments (commands) for all the possible structures and ensure that all text is within these commands. To check that that text is ONLY defined within these macros, you will need to do a two pass: First pass define all the commands to simply ignore any text and typeset the entire document into a \savebox and check that it was empty. – Peter Grill Jun 04 '14 at 22:49
  • Also, if desired, redefine \newcommand/\renewcommand, \newenvironment/\renewenvironment, etc to ensure that users don't easily define any new macros. This way you have complete control of the document. Of course, this assumes that the users are not malicious and don't remove your packages which do this checking. – Peter Grill Jun 04 '14 at 22:52
  • 2
    What are these potential contributors used to editing in? I presume they would be used to Microsoft Word... – Qu0rk Jun 04 '14 at 22:58
  • 1
    I think that commenting the code source with intent and usage can be very helpful. If you have a custom macro, document all of the use cases clearly so that new editors have little need to "tweak" things, just because they didn't understand that their situation was already taken into account. – cslstr Jun 04 '14 at 23:37
  • Of course, this all hinges on "non-proficient" not also implying "unwilling to learn" ... editors should (hopefully) at least attempt to follow the example/guidance of the original author. – cslstr Jun 04 '14 at 23:39
  • 3
    Put any customised macros, environments, commands etc. into a separate class or package and then create a template which shows how to use those custom macros with copious comments. If applicable, remove write permission on both template and class/style so that those can't get accidentally overwritten and comment the top of the template explaining the need to copy the file before editing. That way hopefully the 'canonical' version will be available to new editors so that if inconsistencies do get in, they do not get perpetuated. These can also help to resolve inconsistencies between entries. – cfr Jun 05 '14 at 00:08
  • (+1) Good question. Would a CW answer be appropriate here? – Sean Allred Jun 05 '14 at 04:23
  • 1
    in some similar situations, the separate "entries" for such a composite document have been written in non-tex form as database entries structured in sgml (would now be xml), programmatically checked for validity, then translated. this requires considerable (and often expensive) "machinery" and highly skilled system designers. but worth it for things like aircraft maintenance manuals and the like. i think that attention to good training would be helpful too. – barbara beeton Jun 05 '14 at 12:26

1 Answers1

1

You could use the tool Pandoc. Your users could write and maintain documents in markedown, which is what StackExchange uses, so you know how easy it is to use.

To make this work, you need to design a workflow that takes you from source documents to the final version (LaTex). Ideally, there would be no manual steps in this workflow, so that all changes are made in markdown. If you already have your encyclopedia in LaTex, then you might do a one-time conversion from LaTex to markdown, then do all your future editing on the markdown version.

MrMeritology
  • 111
  • 3