LaTeX Style Guidelines

[mdclyburn]

Initial draft for LaTeX style guidelines.

Feedback appreciated.

[robertu94]

I have been telling people set is the section to look for, but we should double check that all of these rules are followed there before merging.

[robertu94]

We also need to address minification guidelines in this document

[mdclyburn]

Can you list what else there needs to be besides the condensing rules that are already there?

[robertu94]

It's actually #ifdef hackpack and #ifdef hackpackpp

[robertu94]

The part about attempting to leave in index entries if possible.

Also the minified version should include the list of applications.

[robertu94]

I am quite happy with the style guide that we have come up with here. I propose that we go ahead and merge this. Thoughts @ProtractorNinja?

[ProtractorNinja]

• Can you make a note that "Encapsulated PostScript" files are just .eps files?

• The bulleted points aren't composed consistently, although I get the impression that they're intentionally done differently in certain cases. The place that stands out the most is the list under "Things to Keep In Mind", which may as well be replaced with a clone of the General Rules part below. I could be wrong.

• I'm not sure this is the place to discuss this, but why are we forcing sample code to live in an example contest problem? This structure fits as a learning resource, but honestly, our goal right now should be to optimize for a contest environment. Wouldn't it be more useful to have a bare-bones DS/algorithm implementation for quick reference?

  All the sample problem IO/format/etc. junk takes up a lot of space, complicates things when you're trying to find an algorithm during a contest -- it's tough enough thinking about the problem you're currently trying to solve -- and, generally speaking, requiring a sample problem makes contribution more challenging. They just aren't very useful for a contest environment.

  Hence, I think that Algorithm and Data Structure sections should only require Description and Reference sections ("Applications", if actually relevant, should be a sub-section under Description), with Sample Problems as an optional extra for the HackPack++ except in cases of extreme relevance.

[mdclyburn]

• Heh heh. My over-formality. I will add the .eps note.
• I'll look into this and see what I find.
• Oh, boy. Another thing I'd be willing to have an extended conversation about. Perhaps we should open another issue? If you don't, I will.

Thanks a bundle, @ProtractorNinja

[ProtractorNinja]

See #63.

[robertu94]

I am fine with making Applications a subsection of Description; however, I still believe that it is needed:

• It provides a short list of how this is used. Sure you and I both know that Dijkstra solves shortest paths, but did you know that flow helps you find a minimum path decomposition in a DAG? Furthermore, with data structures, this is a more useful question to answer.
• It provides a handy place to include index entries that aren't hidden in a paragraph swamp.

In short, Applications should answer the question, "Why do I care?"

[ProtractorNinja]

I went back to review all of the "Applications" sections, and realized that they're sometimes useful, sometimes not -- for instance, the Graph and Heap chapters list applications in a different sense than what you described. Instead of noting, er, actual applications, they vaguely reference algorithms that use the structure. That's not helpful at all, especially if the referenced material isn't actually in the hack pack.

As neat as it is to know that the Bellman Ford algorithm involves graphs with some negative edges, that information is insultingly useless in a contest environment if I still don't know how to use the Bellman Ford algorithm.

"Applications" should be useful somehow. If you can't actually apply them, then why are they there?

[mdclyburn]

OK. I think I see what you mean @ProtractorNinja. Perhaps the 'Quick Start' section should be moved to the README.md and the CONTRIBUTING.md should remain a comprehensive guide to submitting content?

[ProtractorNinja]

I don't think so, actually -- the Readme should link to CONTRIBUTING, but CONTRIBUTING should be a one-stop shop for all things contribution. A quick reference on the top is handy.

I think my confusion was because 'Things to Keep in Mind' section further reduces something from later on that's already pretty quick to read. I'm not sure how to balance them properly.

[mdclyburn]

OK. I understand.

[ProtractorNinja]

The LaTeX contribution document still suffers due to the as-yet-unaddressed large-scale issues that I wrote about in #63. However, publishing a LaTeX standards guide doesn't need to be held up by those issues--here's some feedback to help get the guide out there:

• The quick start is indeed quick, but somehow feels detached. Perhaps this feeling could be alleviated by rewriting it to be a blend of a quick start and a friendly introduction to the document. As is, the whole thing could benefit from sounding more relaxed.
• I'm still bothered by how there's a mix of bullet grammar and punctuation in contrast to the rest of the document. Can you change the bullets (and context, if necessary) to be properly punctuated?
• The reference section description implies that algorithm sample code is not necessary, but including minimal code would be helpful. This may be a point for High level organization: why aren't we targeting a contest environment? #63.

[mdclyburn]

Oh, feedback!

• I'll look into grooming it into something with a silky-smooth, alluring texture.
• Will do.
• Yeah... about that... (comment below)

Sections of this guide almost definitely depend on what makes for a valid contribution. Until #63 is resolved, parts of this document are in a kind of limbo. We need to know exactly what is going to be contributed before we can decisively know how we want it contributed.

[mdclyburn]

All right, @ProtractorNinja. So, I've made some changes based on what you have commented on. Of course, you're always welcome to make changes to the document yourself. If the new quick start section is distasteful in any way, please feel free to write it yourself.

This guide will change once we get through #63.

[ProtractorNinja]

Looks a lot better. Thanks!