diff options
Diffstat (limited to 'docs/manual.org')
| -rw-r--r-- | docs/manual.org | 142 |
1 files changed, 74 insertions, 68 deletions
diff --git a/docs/manual.org b/docs/manual.org index 3c6de1c..bc58ceb 100644 --- a/docs/manual.org +++ b/docs/manual.org @@ -1,78 +1,81 @@ #+TITLE: 7Units User Manual -#+SUBTITLE: For Version 0.5.0 -#+DATE: 2024 March 23 +#+SUBTITLE: For Version 1.0.0 +#+DATE: 2025 June 1 #+LaTeX_HEADER: \usepackage[a4paper, lmargin=25mm, rmargin=25mm, tmargin=25mm, bmargin=25mm]{geometry} #+LaTeX: \newpage * Introduction and Purpose - 7Units is a program that can be used to convert units. This document outlines how to use the program. +7Units is a program that can be used to convert units. This document outlines how to use the program. * System Requirements - - Works on all major operating systems \\ - *NOTE:* All screenshots in this document were taken on Windows 10. If you use a different operating system, the program will probably look different than what is shown. - - Java version 11+ required -# installation instructions go here - wait until git repository is fixed/set up +- Works on all major operating systems \\ + *NOTE:* All screenshots in this document were taken on Windows 10. If you use a different operating system, the program will probably look different than what is shown. +- Java version 11+ required +- Gradle required +- To run the software, simply run './gradlew run' in the main directory. #+LaTeX: \newpage * How to Use 7Units ** Simple Unit Conversion - 1. Select the "Convert Units" tab if it is not already selected. You should see a screen like in figure [[main-interface-dimension]]: - #+CAPTION: Taken in version 0.3.0 - #+ATTR_LaTeX: :height 250px - #+name: main-interface-dimension - [[../screenshots/main-interface-dimension-converter.png]] - 2. Use the dropdown box at the top to select what kind of unit to convert (length, mass, speed, etc.) - 3. Select the unit to convert /from/ on the left. - 4. Select the unit to convert /to/ on the right. - 5. Enter the value to convert in the box above the convert button. The program should look something like in figure [[sample-conversion-dimension]]: - #+CAPTION: This image, taken in version 0.3.0, shows the user about to convert 35 miles to kilometres. - #+attr_latex: :height 250px - #+name: sample-conversion-dimension - [[../screenshots/sample-conversion-dimension-converter.png]] - 6. Press the "Convert" button. The result will be shown below the "Convert" button. This is shown in figure [[sample-results-dimension]] - #+CAPTION: The result of the above conversion - #+attr_latex: :height 250px - #+name: sample-results-dimension - [[../screenshots/sample-conversion-results-dimension-converter.png]] +1. Select the "Convert Units" tab if it is not already selected. You should see a screen like in figure [[main-interface-dimension]]: + #+CAPTION: Taken in version 0.3.0 + #+ATTR_LaTeX: :height 250px + #+name: main-interface-dimension + [[../screenshots/main-interface-dimension-converter.png]] +2. Use the dropdown box at the top to select what kind of unit to convert (length, mass, speed, etc.) +3. Select the unit to convert /from/ on the left. +4. Select the unit to convert /to/ on the right. +5. Enter the value to convert in the box above the convert button. The program should look something like in figure [[sample-conversion-dimension]]: + #+CAPTION: This image, taken in version 0.3.0, shows the user about to convert 35 miles to kilometres. + #+attr_latex: :height 250px + #+name: sample-conversion-dimension + [[../screenshots/sample-conversion-dimension-converter.png]] +6. Press the "Convert" button. The result will be shown below the "Convert" button. This is shown in figure [[sample-results-dimension]] + #+CAPTION: The result of the above conversion + #+attr_latex: :height 250px + #+name: sample-results-dimension + [[../screenshots/sample-conversion-results-dimension-converter.png]] ** Complex Unit Conversion - 1. Select the "Convert Unit Expressions" if it is not already selected. You should see a screen like in figure [[main-interface-expression]]: - #+CAPTION: Taken in version 0.3.0 - #+attr_latex: :height 250px - #+name: main-interface-expression - [[../screenshots/main-interface-expression-converter.png]] - 2. Enter a [[*Unit Expressions][unit expression]] in the From box. This can be something like "~7 km~" or "~6 ft - 2 in~" or "~3 kg m + 9 lb ft + (35 mm)^2 * (85 oz) / (20 in)~". - 3. Enter a unit name (or another unit expression) in the To box. - 4. Press the Convert button. This will calculate the value of the first expression, and convert it to a multiple of the second unit (or expression). - #+CAPTION: A sample calculation. Divides ~100 km~ by ~35 km/h~ and converts the result to minutes. This could be used to calculate how long (in minutes) it takes to go 100 kilometres at a speed of 35 km/h. - #+attr_latex: :height 250px - #+name: sample-results-expression - [[../screenshots/sample-conversion-results-expression-converter.png]] +1. Select the "Convert Unit Expressions" if it is not already selected. You should see a screen like in figure [[main-interface-expression]]: + #+CAPTION: Taken in version 0.3.0 + #+attr_latex: :height 250px + #+name: main-interface-expression + [[../screenshots/main-interface-expression-converter.png]] +2. Enter a [[*Unit Expressions][unit expression]] in the From box. This can be something like "~7 km~" or "~6 ft - 2 in~" or "~3 kg m + 9 lb ft + (35 mm)^2 * (85 oz) / (20 in)~". +3. Enter a unit name (or another unit expression) in the To box. +4. Press the Convert button. This will calculate the value of the first expression, and convert it to a multiple of the second unit (or expression). + #+CAPTION: A sample calculation. Divides ~100 km~ by ~35 km/h~ and converts the result to minutes. This could be used to calculate how long (in minutes) it takes to go 100 kilometres at a speed of 35 km/h. + #+attr_latex: :height 250px + #+name: sample-results-expression + [[../screenshots/sample-conversion-results-expression-converter.png]] * 7Units Settings - All settings can be accessed in the tab with the gear icon. - #+CAPTION: The settings menu, as of version 0.4.0 - #+ATTR_LaTeX: :height 250px - [[../screenshots/main-interface-settings.png]] +All settings can be accessed in the tab with the gear icon. +#+CAPTION: The settings menu, as of version 0.4.0 +#+ATTR_LaTeX: :height 250px +[[../screenshots/main-interface-settings.png]] ** Rounding Settings - These settings control how the output of a unit conversion is rounded. - - Fixed Precision :: Round to a fixed number of [[https://en.wikipedia.org/wiki/Significant_figures][significant digits]]. The number of significant digits is controlled by the precision slider below. - - Fixed Decimal Places :: Round to a fixed number of digits after the decimal point. The number of decimal places is also controlled by the precision slider below. - - Scientific Precision :: Intelligent rounding which uses the precision of the input value(s) to determine the output precision. Not affected by the precision slider. +These settings control how the output of a unit conversion is rounded. +- Fixed Precision :: Round to a fixed number of [[https://en.wikipedia.org/wiki/Significant_figures][significant digits]]. The number of significant digits is controlled by the precision slider below. +- Fixed Decimal Places :: Round to a fixed number of digits after the decimal point. The number of decimal places is also controlled by the precision slider below. +- Scientific Precision :: Intelligent rounding which uses the precision of the input value(s) to determine the output precision. Not affected by the precision slider. ** Prefix Repetition Settings - These settings control when you are allowed to repeat unit prefixes (e.g. kilokilometre) - - No Repetition :: Units may only have one prefix. - - No Restriction :: Units may have any number of prefixes. - - Complex Repetition :: A complex rule which makes it so that each power of 10 has one and only one prefix combination. Units may have the following prefixes: - - one of: centi, deci, deca, hecto - - one of: zepto, atto, femto, pico, nano, micro, milli, kilo, mega, giga, tera, peta, exa, zetta - - any number of yocto or yotta - - they must be in this order - - all prefixes must be of the same sign (either all magnifying or all reducing) +These settings control when you are allowed to repeat unit prefixes (e.g. kilokilometre) +- No Repetition :: Units may only have one prefix. +- No Restriction :: Units may have any number of prefixes. +- Complex Repetition :: A complex rule which makes it so that each power of 10 has one and only one prefix combination. Units may have the following prefixes: + - one of: centi, deci, deca, hecto + - one of: zepto, atto, femto, pico, nano, micro, milli, kilo, mega, giga, tera, peta, exa, zetta + - any number of yocto or yotta + - they must be in this order + - all prefixes must be of the same sign (either all magnifying or all reducing) ** Search Settings - These settings control which prefixes are shown in the "Convert Units" tab. Only coherent SI units (e.g. metre, second, newton, joule) will get prefixes. Some prefixed units are created in the unitfile, and will stay regardless of this setting (though they can be removed from the unitfile). - - Never Include Prefixed Units :: Prefixed units will only be shown if they are explicitly added to the unitfile. - - Include Common Prefixes :: Every coherent unit will have its kilo- and milli- versions included in the list. - - Include All Single Prefixes :: Every coherent unit will have every prefixed version of it included in the list. +These settings control which prefixes are shown in the "Convert Units" tab. Only coherent SI units (e.g. metre, second, newton, joule) will get prefixes. Some prefixed units are created in the unitfile, and will stay regardless of this setting (though they can be removed from the unitfile). +- Never Include Prefixed Units :: Prefixed units will only be shown if they are explicitly added to the unitfile. +- Include Common Prefixes :: Every coherent unit will have its kilo- and milli- versions included in the list. +- Include All Single Prefixes :: Every coherent unit will have every prefixed version of it included in the list. ** Miscellaneous Settings - - Convert One Way Only :: In the simple conversion tab, only imperial/customary units will be shown on the left, and only metric units[fn:1] will be shown on the right. Units listed in the exceptions file (~src/main/resources/metric_exceptions.txt~) will be shown on both sides. This is a way to reduce the number of options you must search through if you only convert one way. The expressions tab is unaffected. - - Show Duplicates in "Convert Units" :: If unchecked, any unit that has multiple names will only have one included in the Convert Units lists. The selected name will be the longest; if there are multiple longest names one is selected arbitrarily. You will still be able to use these alternate names in the expressions tab. +- Convert One Way Only :: In the simple conversion tab, only imperial/customary units will be shown on the left, and only metric units[fn:1] will be shown on the right. Units listed in the exceptions file (~src/main/resources/metric_exceptions.txt~) will be shown on both sides. This is a way to reduce the number of options you must search through if you only convert one way. The expressions tab is unaffected. +- Show Duplicates in "Convert Units" :: If unchecked, any unit that has multiple names will only have one included in the Convert Units lists. The selected name will be the longest; if there are multiple longest names one is selected arbitrarily. You will still be able to use these alternate names in the expressions tab. +- Use Default Datafiles :: If unchecked, the default units, prefixes and diension names will not be loaded (except for SI base units and their dimensions). +- Locale :: Which language is used for the interface of 7Units. Custom locales can be added. ** Configuration File The settings are saved in a configuration file. On Windows, this is located at \\ ~%USERPROFILE%/AppData/Local/SevenUnits/config.txt~. On other operating systems, this is located at ~$HOME/.config/SevenUnits/config.txt~. The directory containing the ~SevenUnits~ directory can be overridden with the environment variables ~$LOCALAPPDATA~ on Windows or ~$XDG_CONFIG_HOME~ elsewhere. @@ -87,19 +90,22 @@ The possible setting names are: - ~include_duplicates~ :: Whether duplicate units should be shown; can be either ~true~ or ~false~. - ~search_prefix_rule~ :: The prefix search rule; can be ~NO_PREFIXES~, ~COMMON_PREFIXES~, \\ or ~ALL_METRIC_PREFIXES~. +- ~use_default_datafiles~ :: Whether default datafiles should be used; can be either ~true~ or ~false~. +- ~locale~ :: The name of the locale to use. + This is the name of a locale file, excluding the extension, in one of the directories specified in the data specification. For example, if this is 'en', 7Units will look for a file called 'en.txt' in either ~src/main/resources/locales/~ or ~[CONFIG]/locales/~. You can also use the special setting names ~custom_unit_file~, ~custom_dimension_file~ and ~custom_exception_file~ to add custom units, dimensions and metric exceptions to the system. These files use the same format as the standard files. These setting names can be used more than once to include multiple unit, dimension or exception files. * Appendices ** Unit Expressions - A unit expression is simply a math expression where the values being operated on are units or numbers. The operations that can be used are (in order of precedence): - - Exponentiation (^); the exponent must be an integer. Both units and numbers can be raised to an exponent - - Multiplication (*) and division (/). Multiplication can also be done with a space (so "15 meter" is the same thing as "15 * meter"). - You can also divide with ~|~ to create fractions. Using ~|~ instead of ~/~ gives the division a higher precedence than any other operator. For example, "2|5^2" evaluates to 4/25, not 2/25. - - Addition (+) and subtraction (-). They can only be done between units of the same dimension (measuring the same thing). So you can add metres, inches and feet together, and you can add joules and calories together, but you can't add metres to seconds, or feet to calories, or watts to pounds. +A unit expression is simply a math expression where the values being operated on are units or numbers. The operations that can be used are (in order of precedence): +- Exponentiation (^); the exponent must be an integer. Both units and numbers can be raised to an exponent. +- Multiplication (*) and division (/). Multiplication can also be done with a space (so "15 meter" is the same thing as "15 * meter"), and multiplication using spaces has higher precedence than division. Therefore, "2 m / 1 m" is the number 2, while "2 * m / 1 * m" is equal to 2 m^2. + You can also divide with ~|~ to create fractions. Using ~|~ instead of ~/~ gives the division a higher precedence than any other operator. For example, "2|5^2" evaluates to 4/25, not 2/25. +- Addition (+) and subtraction (-). They can only be done between units of the same dimension (measuring the same thing). So you can add metres, inches and feet together, and you can add joules and calories together, but you can't add metres to seconds, or feet to calories, or watts to pounds. *You must use spaces between terms when adding or subtracting - "1 + 2" is valid, "1+2" is not. This only applies to addition and subtraction - other operators do not need spaces between them.* This is done to avoid complex rules when working with negative numbers and e-notation. - Brackets can be used to manipulate the order of operations, and nonlinear units like Celsius and Fahrenheit cannot be used in expressions. You can use a value in a nonlinear unit by putting brackets after it - for example, degC(12) represents the value 12 \deg C + Brackets can be used to manipulate the order of operations, and nonlinear units like Celsius and Fahrenheit cannot be used in expressions. You can use a value in a nonlinear unit by putting brackets after it - for example, degC(12) represents the value 12 \deg{}C ** Other Expressions - There are also a simplified version of expressions for prefixes and dimensions. Only multiplication, division and exponentation are supported. Currently, exponentation is not supported for dimensions, but that may be fixed in the future. +There are also a simplified version of expressions for prefixes and dimensions. Only multiplication, division and exponentation are supported. Currently, exponentation is not supported for dimensions, but that may be fixed in the future. * Footnotes -[fn:1] 7Units's definition of "metric" is stricter than the SI, but all of the common units that are commonly considered metric but not included in 7Units's definition are included in the exceptions file. +[fn:1] 7Units's definition of "metric" is stricter than the SI, but all of the common units that are commonly considered metric but not included in 7Units's definition are included in the exceptions file. |