search

geodynamics / best_practices

Software development and training best practices.
13 stars 9 forks source link

Add CIG software manual template #10

Closed naliboff closed 5 years ago

baagaard-usgs commented 5 years ago

This would be a lot easier to use if it was split between a LaTeX class file (.cls) with all of the macros and commands defined and an example LaTeX file (.tex) file that makes use of the class.

naliboff commented 5 years ago

@baagaard-usgs I remember seeing a discussion about this on an email chain, but don't recall if there was a final consensus. I have no strong preference either way.

ljhwang commented 5 years ago

I think there was a slight bias to having everything in one file but no strong objection if someone made a pull request separating the two.

naliboff commented 5 years ago

Thoughts for moving forward? I don't think we should maintain two separate versions, which either use or don't use an additional .cls file.

One option would be to put a detailed note in the .tex file explaining that many of the commands could be moved to a .cls file and point to the PyLith manual as an example of how to do so.

If there is a strong group preference to put the macros in a .cls file, happy to do so.

baagaard-usgs commented 5 years ago

I strongly favor a .cls file because it makes the .tex file simpler and easier to understand and leaving formatting commands in the .tex file just invites people to change them, which negates much of the purpose of a "template."

jedbrown commented 5 years ago

Agree if someone is willing to maintain the *.cls file.

naliboff commented 5 years ago

@baagaard - When I get a chance next week I'll take a first pass at making a .cls file and then follow up with another PR.