From 4d6bbf7829e6d7a23b5cc59b4c0770f7dd16087b Mon Sep 17 00:00:00 2001 From: twanvl Date: Fri, 13 Jul 2007 17:54:10 +0000 Subject: [PATCH] Documentation of script functions and file types (work in progress) git-svn-id: svn://svn.code.sf.net/p/magicseteditor/code/trunk@564 0fc631ac-6414-0410-93d0-97cfa31319b6 --- doc/README | 4 + doc/about/index.txt | 23 ++ doc/about/license.txt | 384 +++++++++++++++++++++++++++++++ doc/file/index.txt | 0 doc/function/filter_list.txt | 0 doc/function/index.txt | 71 ++++++ doc/function/number_of_items.txt | 0 doc/function/position.txt | 25 ++ doc/function/sort_list.txt | 0 doc/index.txt | 15 ++ doc/script/index.txt | 2 + doc/script/operators.txt | 0 doc/script/syntax.txt | 0 doc/type/color.txt | 15 ++ doc/type/combine.txt | 7 + doc/type/game.txt | 0 doc/type/index.txt | 48 ++++ doc/type/list.txt | 28 +++ doc/type/regex.txt | 0 doc/type/set.txt | 85 +++++++ doc/type/string.txt | 5 + doc/type/stylesheet.txt | 12 + doc/type/tagged_string.txt | 37 +++ doc/type/value.txt | 1 + 24 files changed, 762 insertions(+) create mode 100644 doc/README create mode 100644 doc/about/index.txt create mode 100644 doc/about/license.txt create mode 100644 doc/file/index.txt create mode 100644 doc/function/filter_list.txt create mode 100644 doc/function/index.txt create mode 100644 doc/function/number_of_items.txt create mode 100644 doc/function/position.txt create mode 100644 doc/function/sort_list.txt create mode 100644 doc/index.txt create mode 100644 doc/script/index.txt create mode 100644 doc/script/operators.txt create mode 100644 doc/script/syntax.txt create mode 100644 doc/type/color.txt create mode 100644 doc/type/combine.txt create mode 100644 doc/type/game.txt create mode 100644 doc/type/index.txt create mode 100644 doc/type/list.txt create mode 100644 doc/type/regex.txt create mode 100644 doc/type/set.txt create mode 100644 doc/type/string.txt create mode 100644 doc/type/stylesheet.txt create mode 100644 doc/type/tagged_string.txt create mode 100644 doc/type/value.txt diff --git a/doc/README b/doc/README new file mode 100644 index 00000000..61c7b8df --- /dev/null +++ b/doc/README @@ -0,0 +1,4 @@ +doc/* + +This directory contains the Magic Set Editor technical documentation, as shown on the website. +The files are converted to HTML using the 'autoformat' php script in tools/website/drupal. diff --git a/doc/about/index.txt b/doc/about/index.txt new file mode 100644 index 00000000..cd44af75 --- /dev/null +++ b/doc/about/index.txt @@ -0,0 +1,23 @@ +Magic Set Editor credits + +! Programming <<< +| [[user/1|Twan van Laarhoven]] Main developer +| [[user/430|coppro]] Linux programmer + +! Template development <<< +| [[user/14|Pichoro]] Template maintainer, keywords and lots more +| Artfreakwiu Old style tokens, VS System, Pokemon, split cards +| Guinea Pig Hybrid blending masks, Non-creature flip cards +| TheWarden Collecting template images +| Basilisk Card frames +| Jeff Torres (Wolfwood) Vanguard, Flip cards, split cards +| JrEye Magic keyword list +| Neko_Asakami Multicolor blended flip cards, keywords + +! Resources and libraries <<< +| [[http://boost.org|Boost]] Boost C++ library +| [[http://wxwidgets.org|wxWidgets]] GUI library +| [[http://famfamfam.com/lab/icons/silk/|Mark James]] Icons for the program + +! Alpha and beta testing <<< +| ''Too many people to mention!'' <<< diff --git a/doc/about/license.txt b/doc/about/license.txt new file mode 100644 index 00000000..3557979b --- /dev/null +++ b/doc/about/license.txt @@ -0,0 +1,384 @@ +GNU General Public License + +Magic Set Editor is licensed under the GNU General Public License version 2 or later + + +==Table of Contents== +* GNU GENERAL PUBLIC LICENSE + * Preamble + * TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + * How to Apply These Terms to Your New Programs + +
+ +Version 2, June 1991 + +]Copyright (C) 1989, 1991 Free Software Foundation, Inc. +]51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA +] +]Everyone is permitted to copy and distribute verbatim copies +]of this license document, but changing it is not allowed. + +==Preamble== + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + +==TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION== + +0. + This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +1. + You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +2. + You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +;a) +; You must cause the modified files to carry prominent notices +; stating that you changed the files and the date of any change. + + +;b) +; You must cause any work that you distribute or publish, that in +; whole or in part contains or is derived from the Program or any +; part thereof, to be licensed as a whole at no charge to all third +; parties under the terms of this License. + + +;c) +; If the modified program normally reads commands interactively +; when run, you must cause it, when started running for such +; interactive use in the most ordinary way, to print or display an +; announcement including an appropriate copyright notice and a +; notice that there is no warranty (or else, saying that you provide +; a warranty) and that users may redistribute the program under +; these conditions, and telling the user how to view a copy of this +; License. (Exception: if the Program itself is interactive but +; does not normally print such an announcement, your work based on +; the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +3. + You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + +;a) +; Accompany it with the complete corresponding machine-readable +; source code, which must be distributed under the terms of Sections +; 1 and 2 above on a medium customarily used for software interchange; or, + + +;b) +; Accompany it with a written offer, valid for at least three +; years, to give any third party, for a charge no more than your +; cost of physically performing source distribution, a complete +; machine-readable copy of the corresponding source code, to be +; distributed under the terms of Sections 1 and 2 above on a medium +; customarily used for software interchange; or, + + +;c) +; Accompany it with the information you received as to the offer +; to distribute corresponding source code. (This alternative is +; allowed only for noncommercial distribution and only if you +; received the program in object code or executable form with such +; an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +4. + You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +5. + You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +6. + Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +7. + If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + +8. + If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + +9. + The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + +10. + If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + +NO WARRANTY + + +11. + BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + +12. + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + +==END OF TERMS AND CONDITIONS== + + +==How to Apply These Terms to Your New Programs== + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + +] +] Copyright (C) +] +] This program is free software; you can redistribute it and/or modify +] it under the terms of the GNU General Public License as published by +] the Free Software Foundation; either version 2 of the License, or +] (at your option) any later version. +] +] This program is distributed in the hope that it will be useful, +] but WITHOUT ANY WARRANTY; without even the implied warranty of +] MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +] GNU General Public License for more details. +] +] You should have received a copy of the GNU General Public License +] along with this program; if not, write to the Free Software +] Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +] Gnomovision version 69, Copyright (C) year name of author +] Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. +] This is free software, and you are welcome to redistribute it +] under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + +] Yoyodyne, Inc., hereby disclaims all copyright interest in the program +] `Gnomovision' (which makes passes at compilers) written by James Hacker. +] +] , 1 April 1989 +] Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/doc/file/index.txt b/doc/file/index.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/function/filter_list.txt b/doc/function/filter_list.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/function/index.txt b/doc/function/index.txt new file mode 100644 index 00000000..9cc9358a --- /dev/null +++ b/doc/function/index.txt @@ -0,0 +1,71 @@ +Script functions by category + +These functions are built into the program, other [[type:function]]s can be defined using the scripting language. + +! Text manipulation <<< +| [[fun:to_upper]] Convert a string to upper case, @"aBc" -> "ABC"@. +| [[fun:to_lower]] Convert a string to lower case, @"aBc" -> "abc"@. +| [[fun:to_title]] Convert a string to title case, @"aBc" -> "Abc"@. +| [[fun:reverse]] Reverse a string, @"aBc" -> "cBa"@. +| [[fun:substring]] Extract a part of a string. +| [[fun:format]] Format a number as a string (printf). +| [[fun:format_rule]] ^^^ +| [[fun:curly_quotes]] Make quotes curly. +| [[fun:replace]] Replace text matching a regular expression. +| [[fun:replace_rule]] ^^^ +| [[fun:filter_text]] Keep only the text matching a regular expression. +| [[fun:filter_rule]] ^^^ +| [[fun:sort_text]] Sort the letters in a string using a custom order. +| [[fun:sort_rule]] ^^^ +| [[fun:contains]] Does a string contain another one? +| [[fun:match]] Does a string match a regular expression? +| [[fun:match_rule]] ^^^ +! [[type:tagged_string|Tags]] <<< +| [[fun:tag_contents]] Change the contents of a specific tag. +| [[fun:tag_contents_rule]] ^^^ +| [[fun:remove_tag]] Remove a tag, keep the contents. +| [[fun:tag_remove_rule]] ^^^ +! [[type:list|Lists]] <<< +| [[fun:position]] Find the position of an element in a list. +| [[fun:number_of_items]] Find the number of items in a list. +| [[fun:sort_list]] Sort a list. +| [[fun:filter_list]] Filter a list, keeping only elements that match a predicate. + +! Keywords <<< +| [[fun:expand_keywords]] Expand the keywords in a piece of text. +| [[fun:expand_keywords_rule]] ^^^ +| [[fun:keyword_usage]] What keywords are used on a card, and how often are they used? + +! English language <<< +| [[fun:english_number]] Convert a number to text (@"one"@, @"two"@, ''etc.'') +| [[fun:english_number_a]] Convert a number to text (@"a"@, @"two"@, ''etc.'') +| [[fun:english_number_multiple]] Convert a number to text (@""@, @"two"@, ''etc.'') +| [[fun:english_number_ordinal]] Convert a number to text (@"first"@, @"second"@, ''etc.'') +| [[fun:english_plural]] Find the plural of a word, @"card" -> "cards"@. +| [[fun:english_singular]] Find the singular of a word, @"cards" -> "card"@. +| [[fun:process_english_hints]] Process the hints left by english_ functions in a keyword's reminder text. + +! Fields and values <<< +| [[fun:combined_editor|forward_editor]] Use one field to edit another. +| [[fun:combined_editor]] Use one field to edit multiple others. +| [[fun:primary_choice]] Return the top level choice chosen from a choice field. +| [[fun:chosen]] Is the given choice selected in a multiple choice value? +| [[fun:require_choice]] Require that at least one of the given choices is selected. +| [[fun:exclusive_choice]] Require that at most one of the given choices is selected. +| [[fun:require_exclusive_choice]] Require that exactly one of the given choices is selected. +| [[fun:remove_choice]] Remove the given choices from a multiple choice value. + +! Images <<< +| [[fun:linear_blend]] Blend two images together using a linear gradient. +| [[fun:masked_blend]] Blend two images together using a third mask image. +| [[fun:combine_blend]] Blend two images together using a given [[type:combine|combining mode]]. +| [[fun:set_mask]] Set the transparancy mask of an image. +| [[fun:set_alpha]] Change the transparency of an image. +| [[fun:set_combine]] Chnage how the image should be combined with the background. +| [[fun:enlarge]] Enlarge an image by putting a border around it. +| [[fun:drop_shadow]] Add a drop shadow to an image. +| [[fun:symbol_variation]] Render a variation of a [[type:symbol]]. +| [[fun:built_in_image]] Return an image built into the program. + +! Other functions <<< +| [[fun:trace]] Output a message for debugging purposes. diff --git a/doc/function/number_of_items.txt b/doc/function/number_of_items.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/function/position.txt b/doc/function/position.txt new file mode 100644 index 00000000..3c7f7c31 --- /dev/null +++ b/doc/function/position.txt @@ -0,0 +1,25 @@ +Function: position + +--Usage-- +> position(of: some_item, in: some_list) + +Returns the position of an item in a list. +The first position is @0@. +If the item is not found in the list, returns @-1@. + +--Parameters-- +| @of@ ''anything'' Item to look for. +| @in@ [[type:list]] or [[type:set]] List to look in. + Can be a [[type:set]] when looking for a card. +| @order_by@ [[type:function]] (optional) Find the position as if the list was [[fun:sort_list|sorted]] by this criterion. + Only when looking in a set. +| @filter@ [[type:function]] (optional) Find the position as if the list was [[fun:filter_list|filtered]] by this criterion. + Only when looking in a set. + +--Examples-- +> postion(of: "x", in: ["x", "y", "z"]) == 0 +> postion(of: "z", in: ["x", "y", "z"]) == 2 +> postion(of: "a", in: ["x", "y", "z"]) == -1 +> +> # The position of the card in the list of red cards, ordered by name +> postion(of: card, in: set, order_by: {card.name}, filter:{card.color == "red"}) diff --git a/doc/function/sort_list.txt b/doc/function/sort_list.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 index 00000000..89233ed9 --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,15 @@ +Documentation + +Welcome to the Magic Set Editor technical documentation. +These documents describe the file formats and scirpting language used by the program. + +--Topics-- +* [[doc/tutorial|Templating tutorial]] (comming soon) +* [[doc/file|File formats]] +* [[doc/type|Data types used in the files]] +* [[doc/script|Scripting language overview]] +* [[doc/function|Script function reference]] + +--Other information-- +* [[doc/about|MSE credits]] +* [[doc/about/license|License]] diff --git a/doc/script/index.txt b/doc/script/index.txt new file mode 100644 index 00000000..40e44c6b --- /dev/null +++ b/doc/script/index.txt @@ -0,0 +1,2 @@ +Scripting language + diff --git a/doc/script/operators.txt b/doc/script/operators.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/script/syntax.txt b/doc/script/syntax.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/color.txt b/doc/type/color.txt new file mode 100644 index 00000000..ba302a84 --- /dev/null +++ b/doc/type/color.txt @@ -0,0 +1,15 @@ +==Data type: color== + +--Syntax-- +In files and scritps a color can be represented as +
rgb(red_component, green_component, blue_component)
+where red_component, green_component and blue_component are numbers between 0 and 255 (inclusive). + +--Examples-- +For example: +! Code Represents +| @rgb(255,255,255)@ white, +| @rgb(0,0,0)@ black, +| @rgb(255,0,0)@ red, +| @rgb(0,255,0)@ green, +| @rgb(0,0,255)@ blue, diff --git a/doc/type/combine.txt b/doc/type/combine.txt new file mode 100644 index 00000000..506d274f --- /dev/null +++ b/doc/type/combine.txt @@ -0,0 +1,7 @@ +==Data type: image combine type== + +This specifies how an image is to be combined with the background. +This is similair to the feature found in more advanced drawing programs. + +--Possible values-- +| overlay \ No newline at end of file diff --git a/doc/type/game.txt b/doc/type/game.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/index.txt b/doc/type/index.txt new file mode 100644 index 00000000..7c106db7 --- /dev/null +++ b/doc/type/index.txt @@ -0,0 +1,48 @@ +Data types + +Magic Set Editor uses many data types in the files and in scripting. +There are for instance [[type:card]]s in [[type:set]]s, [[type:stylesheet]]s describing the layout of [[type:field]]s, etc. + +--Styling trinity-- + +--File types-- +These are the 'major' data types that are written directly to [[file:package]]s. +| [[type:game]] What information is on each card? +| [[type:stylesheets]] What do cards look like? +| [[type:set]] Sets of cards. +| [[type:symbol_font]] Fonts consisting of symbols, for instance mana symbols. +| [[type:export_template]] How to export sets to HTML files? +| [[type:locale]] Translations of MSE. +| [[type:include]] Files to include in other templates. +| [[type:installer]] Installers containing several packages. +| [[type:symbol]] Expansion symbols. +| [[type:settings]] MSE settings. + +--Compound types-- +These contain several properties, similair to the file types. But they are part of some other file type. +| [[type:field]] A field description for cards. +| [[type:style]] The styling and positioning of a field. +| [[type:value]] The value in a field, for a particular card. +| [[type:card]] A card containing values. +| [[type:keyword]] A keyword. +| [[type:font]] Description of a font. +| [[type:script]] A script to execute to update a field, or for initialization. +| [[type:symbol_part]] Part of a [[type:symbol]]. + +--Collection types-- +| [[type:list]] Lists of items + * item + * item + * item +| [[type:indexmap|'index' map]] Lists indexed by field name + +
name:someone
type:something
+| [[type:map]] Lists indexed by other text + +--Primitive types-- +| [[type:string]] Text, @"abc"@ +| [[type:int]] Integer numbers, @1, 2, 100@ +| [[type:double]] Real numbers, @1, 0.5, 21.3@ +| [[type:color]] Colors +| [[type:scriptable]] A primitive type whose value can depend on a script. +| [[type:function]] Functions in scripts. These have no direct representation in a file. diff --git a/doc/type/list.txt b/doc/type/list.txt new file mode 100644 index 00000000..1972fb8f --- /dev/null +++ b/doc/type/list.txt @@ -0,0 +1,28 @@ +Data type: Lists + +--File syntax-- +In files a list is represented as multiple keys, one for each element. +The keys are all in the singular for of the name of the list, +if the list is named for instance @symbols@ each key will be named @symbol@. +] symbol: +] # first symbol here +] symbol: +] # second symbol here +] # etc. + +--Script syntax-- +In a script lists can be declared using square brackets. +> [] # An empty list +> [1] # A list with a single element, the value 1 +> [1,2] # A list with two elements + +Lists can be accessed using either the bracket operator, or the dot operator. +The first element of a list is numbered 0, the next 1, etc. +> list.0 # The first element of the list 'list' +> list[0] # The same thing + +There are several functions for working with lists: +| [[fun:position]] Find the position of an element in a list +| [[fun:number_of_items]] Find the number of items in a list +| [[fun:sort_list]] Sort a list +| [[fun:filter_list]] Filter a list, keeping only elements that match a predicate diff --git a/doc/type/regex.txt b/doc/type/regex.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/set.txt b/doc/type/set.txt new file mode 100644 index 00000000..67387f46 --- /dev/null +++ b/doc/type/set.txt @@ -0,0 +1,85 @@ +==Object type: Set== + +--Package-- +A set is described in a package with the .mse-set file extension, +such a package contains a data file called set. + +--Properties-- +| game Name of a [[type:game]] The game this set is made for. +| stylesheet Name of a [[type:stylesheet]] The default style for drawing cards in this set. +| set info [[type:indexmap]] of [[type:value]]s The data for the [[prop:game:set fields]] defined in the game. +| styling [[type:indexmap]] of [[type:value]]s +| cards [[type:list] of [[type:card]]s The cards in the set. + +--Example-- + +|- +| set info: +| Contains custom information about the set, corresponding to the set fields in the game. +|- +| extra set info: +| Contains information about the set for a specific style, corresponding to the extra fields in the style.
+ Stored with an index for the game, see the example below. +|- +| card:
card:
... +| Contains information about each card, corresponding to the card fields in the game. +|- +| keyword:
keyword:
... +| Extra keywords specific to this set, in addition to those defined in the game. + For more information see the game file +|} + +The set info and cards contain a list of keys that correspond to the names fields in the game, +For example if the game looks like: + name: my game + set field: + name: copyright + type: text + card field: + name: card name + type: text + card field: + name: power + type: text + +The the set file looks like: + game: my game + name: my set + set info: + copyright: something + extra set info: + name-of-style: + name-of-field: something + card: + card name: first card + power: 100 + card: + card name: second card + power: 50 + + +The value that is stored depends on the type of field of course, in the above example the fields have type: text, so the value is just the text. +For other types of fields the value is encoded as follows: +{| +! Attribute !! Description +|- +| text +| The text that is stored in the field. This text can contain tags. +|- +| choice +| One of the choices specified in the game. +|- +| boolean +| One of yes or no. +|- +| color +| The color is encoded as rgb(red,green,blue) where red, green and blue are numbers between 0 and 255 that indicate the color components. +|- +| image +| The filename containing the image, this file must also be in the set package. It can be empty to indicate that no image is selected. +|- +| symbol +| The filename containing the symbol specification, this file must also be in the set package. + It can be empty to indicate that no symbol is selected. +|} +If a field has the default value (calculated by the default script), then the field name and value are ommited from the set file. diff --git a/doc/type/string.txt b/doc/type/string.txt new file mode 100644 index 00000000..6f11b43a --- /dev/null +++ b/doc/type/string.txt @@ -0,0 +1,5 @@ +==Data type: character string== + +--File syntax-- + +--Script syntax-- \ No newline at end of file diff --git a/doc/type/stylesheet.txt b/doc/type/stylesheet.txt new file mode 100644 index 00000000..33c8863f --- /dev/null +++ b/doc/type/stylesheet.txt @@ -0,0 +1,12 @@ +Object type: Stylesheet + +--Properties-- +| @game@ Name of a [[type:game]] Game this stylesheet is made for +| @init script@ [[type:script]] +| @card width@ [[type:double]] Width of cards in pixels +| @card height@ [[type:double]] Height of cards in pixels +| @card dpi@ [[type:double]] Resoltion of cards in dots-per-inch +| @card background@ [[type:color]] Background color of cards +| @card style@ [[type:indexmap] of [[type:style]]s Styles for the [[property:game:card fields]] defined in the game +| + diff --git a/doc/type/tagged_string.txt b/doc/type/tagged_string.txt new file mode 100644 index 00000000..c51282ef --- /dev/null +++ b/doc/type/tagged_string.txt @@ -0,0 +1,37 @@ +==Data type: string with tags== + +--Syntax-- +&1; + +--Basic markup-- +! Tag Description +| The text inside the tag is bold. +| The text inside the tag is italic. +| The text inside the tag is rendered as symbols, if a [[prop:style:symbol font]] is set for the text box. +| Line breaks inside this tag use the [[prop:style:line height line]], and they show a horizontal line. +| Line breaks inside this tag use the [[prop:style:soft line height]]. +| An atomic piece of text. The cursor can never be inside it; it is selected as a whole. + The program automatically inserts +| The text inside the text is rendered in a monospace font. This is used for syntax highlighting script code. +| The text inside the text is highlighted as a keyword in source code. +| The text inside the text is highlighted as a string in source code. + + +--Other tags-- +! Tag Description +| Indicates that the text inside it is a keyword. This tag is automatically inserted by + The [[fun:expand_keywords] function. There are four versions, indicating whether or not reminder text is shown + | Reminder text hidden, by default + | Reminder text shown, by default + | Remder hidden manually + | Remder shown manually +| A separator between fields. This tag is automatically inserted by the [[fun:combined_editor]] function. + Inserting this tag manually will confuse that function! + This tag can never be selected, and its contents can not be edited. +| Like <sep>, only hidden. This is inserted by [[fun:combined_editor]] + ... +| any other tag Other tags are ignored. + +--Related functions-- +The following script functions deal with tags: +| [[fun:remove_tag]] diff --git a/doc/type/value.txt b/doc/type/value.txt new file mode 100644 index 00000000..3a8b4035 --- /dev/null +++ b/doc/type/value.txt @@ -0,0 +1 @@ +== Object type: Field value ==