diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6924f23 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,220 @@ +# LaTeX Standards + +## Quick Start - What Should I Know Getting Started? + +The Hack Pack is an amalgam of algorithms, data structures, and all sorts of handy tidbits intended for use in a programming contest environment. +Contributions are very much appreciated. +Content for the Hack Pack is written in LaTeX. +To contribute a section for the Hack Pack, your submission should include: + +- a description. +- reference code showcasing capabilities. +- a list of applications for the algorithm/data structure. +- sample problem using the algorithm/data structure (with sample format and I/O). + +To keep the document well-organized, there is a set of commands designated for use to mark each part of the Hack Pack. +The 'Sectioning' section lists the appropriate sectioning commands to use for each portion of a section. + +It is possible to create two versions of the document. +One is a more informative, but heavyweight document that includes all information about a topic possible. +The other is a more compact document that excludes information that is likely unwanted in a contest environment. +They are referred to as the 'Hack Pack++' and 'Hack Pack' respectively. +Each section of the Hack Pack needs to properly slim itself down when the leaner version is created. +We have a special method to enable this. +Please wrap content appropriate for only the full-sized Hack Pack++ with `% #ifdef hackpackpp` and `% #endif`. +Wrap content appropriate for only the condensed Hack Pack with `% #ifdef hackpack` and `% #endif`. +Any content that is to appear in both versions of the Hack Pack does not need to be wrapped with anything. + +See the Content section for more information. + +### Things to Keep In Mind + +Please remember to: +- one line for each sentence. +- indent using tabs only. + +## Content - What Goes Into a Section? + +### Sections on Algorithms and Data Structures + +The following subsections __must__ be present before a section will be considered for inclusion: + +- Description +- Reference (only for data structures) +- Applications +- Sample Problem + - Input Format + - Sample Input + - Output Format + - Sample Output + - 'Lessons Learned' + +#### Description + +All data structures and algorithms should include a description section detailing: +- what it does. +- the problem(s) that it solves. +- how it works. +- construction and run times in O-notation. + +#### Reference + +Each section should include a subsection containing skeleton reference code. +The reference code should include only what is necessary to use the data structure and perhaps usage examples in a main function if its use is not obvious enough. + +#### Applications + +A list of uses for the algorithm or data structure. +For example, one application of a maximum flow algorithm is 'finding a minimum set of edges to disconnect a source and sink'. + +#### Sample Problem + +A problem whose solution utilizes the algorithm or data structure the section describes. +Each problem should include a description that _clearly_ describes the problem. Following the problem description should be as follows: + +##### Input Format + +A precise description of the input that will be supplied to the code that will solve the problem described. + +##### Sample Input + +An example input that fully demonstrates and conforms to the format described in 'Input Format'. +Use the `\acmlisting` command to insert your sample input. +See the 'Code Listings' + +##### Output Format + +A precise description of the output that should be produced from the code that will solve the problem described. + +##### Sample Output + +An example input that conforms to the format described in 'Output Format'. +Use the `\acmlisting` command to insert your sample output. +See the 'Code Listings' section under 'Format' for more information. + +##### Sample Solution + +A solution for the problem described. +All solutions should be written in C++ __before__ providing solutions in other languages. + +##### Lessons Learned + +An unordered list of at least one non-trivial observation you had while writing the solution to your sample problem. + +*** + +### Figures and Images + +If adding a visual to a section would greatly aid in the understanding of the topic, doing so is highly encouraged. +Submissions should preferably be in the Encapsulated PostScript format. +This provides very clear visuals, even when scaled up or down. +Do _not_ simply pull images from the Internet. +Doing so may violate the Hack Pack licensing terms. +Any submission found to be doing so will be rejected until the appropriate changes are made. + +Recommended tools: + +- Ipe +- Xfig + +### Indexing + +Indexing entries is very helpful for finding relevant entries in the Hack Pack. +Please do not sprinkle index entries _too_ liberally throughout, as this will cause the size of the index to explode and make it harder to locate information. +If an index entry for the term you are looking to add already exists, add it anyway. +It is possible that a reader may be searching for your section. +An example of a good set of index entries can be found in the section on the Sieve of Eratosthenes. +Entries include: + +- sieve +- primes +- Eratosthenes + +### Citations + +Information pulled from other sources needs to be properly cited. +Any information included in submissions that is not properly cited will cause the entire section to be rejected from consideration for inclusion. +References should use BibTeX where applicable. + +## Format - How Should My LaTeX Look? + +### General Rules to Type By + +Please, remember to: +- use only one sentence per line. +- use tabs for indentation. +- not use LaTeX comments (this excludes primarily technical parts like `style.tex`). + +### Indentation + +Please use one tab per indent. +Any text wrapped in the `\begin{}` and `\end{}` commands should be indented; this includes lists (both itemize and description). + +### Sectioning + +All sections should have headers using the appropriate LaTeX sectioning commands: + +| Section | Command | +|---------|:-------:| +| section title | `\section{}` | +| Applications | `\subsection{}` | +| Sample Problem | `\subsection{}` | +| Input Format | `\subsubsection{}` | +| Sample Input | `\subsubsection{}` | +| Output Format | `\subsubsection{}` | +| Sample Output | `\subsubsection{}` | +| Lessons Learned | `\subsubsection{}` | + +### Code Listings + +Always use the `\acmlisting` command when including code, input, or output in the Hack Pack. +The label and caption should always be set as well; both should be set to the same value. +A code listing for a sample problem titled 'Cows Amok' would be inserted like so: + +`\acmlisting[label=Cows Amok, caption=Cows Amok]{./path/to/cows-amok.cpp}` + +Sample input for the problem would be inserted like so: + +`\acmlisting[label=Cows Amok Sample Input, caption=Cows Amok Sample Input]{./path/to/cows-amok.in}` + +Sample output for the problem would be inserted like so: + +`\acmlisting[label=Cows Amok Sample Output, caption=Cows Amok Sample Output]{./path/to/cows-amok.out}` + +### Style Changes + +Any changes to the style of the document must be cleared with the core Hack Pack team before implementing. +Any submissions that change the style of document (even if not global) without prior approval will be rejected. + +## Condensing - How Is This 'Condensing' Done? + +Each submission to the Hack Pack must also have a condensed version for inclusion in the condensed Hack Pack as well. +This is trivial. + +### Content + +A complete, condensed section of the Hack Pack should include: + +- a brief description of the problem (possibly gleaned from the full description). +- a list of applications. +- reference code (if the section is for a data structure). +- sample solutions for each included problem. + +### How To Condense Your Section + +We have defined special keywords (from a familiar language) to separate information that should be displayed in each section: `#ifdef hackpack`, `#ifdef hackpackpp`, and `#endif`. +Wrap a section with the `#ifdef hackpack` and `#endif` to include the section only in the condensed version of the Hack Pack. +Wrap a section with the `#ifdef hackpack` and `#endif` to include the section only in the full version of the Hack Pack. +Any section that is not wrapped with either set of keywords will be included in both versions of the Hack Pack. +Ensure that index entries are present in both versions of the Hack Pack. + +## Submission - What Should I Do Before Submitting? + +Before submitting a section for inclusion in the Hack Pack, ensure that both the Hack Pack and Hack Pack++ build (using only `make`) on the McAdams lab machines _without stopping_. + +## Still Not Sure? + +We strive to make our content as clear and concise as possible, but it is always possible that we have left some content off. +If you have any question about any part of your LaTeX, it is always a good idea to consult entries that have already made it into the Hack Pack. +In particular, the section on sets is an example of an excellent addition to the Hack Pack. +Failing that, feel free to email any of the Hack Pack development team, `@clemsonacm/hackpack-developers`. diff --git a/README.md b/README.md index 4b475a3..c7aefd5 100644 --- a/README.md +++ b/README.md @@ -89,31 +89,9 @@ All examples assume a topic called `foo` and a sample problem `bar`: + `bar-test.in` Data for the automated unit test + `bar-test.out` Expected output for the automated unit test +#### Writing Documentation - - - -#### Writing Documentation -Documentation should be written in `LaTeX`: -For each item in the Hackpack, please include the following in clearly delineated subsections: - -1. Name and Brief Description of the topic -2. Data structures should have a "Reference" section with a code sample of only commonly used functions -3. A list of possible uses and applications -4. 2-3 possible contest problems; preferably of varying difficulty -5. Sample code that answers one of the contest problems -6. Please use the `\acmlisting` for code listings. A caption and label should be specified. If applicable, line ranges should be specified to limit the amount of text displayed. -7. It would be preferred if each set of sample code had some lessons learned to point out some key elements of the implementation -8. References using BibTeX where applicable -9. Should be "compiled" properly by make -10. Each sentence must be on a separate line. -11. The condensed version of the hackpack should have the following removed: - - * Introductions to the topic. - * Guidelines directing the reader to different sections of the hackpack. - * References to contest problems including statement, sample io, and - lessons learned, but solutions should remain. - * As much as possible, index tags should __NOT__ be removed. +Please see CONTRIBUTING.md for guidelines concerning documentation. #### Writing Code Code Must meet the following standards: