Mercurial > hg > xemacs-beta
annotate man/custom.texi @ 4952:19a72041c5ed
Mule-izing, various fixes related to char * arguments
-------------------- ChangeLog entries follow: --------------------
modules/ChangeLog addition:
2010-01-26 Ben Wing <ben@xemacs.org>
* postgresql/postgresql.c:
* postgresql/postgresql.c (CHECK_LIVE_CONNECTION):
* postgresql/postgresql.c (print_pgresult):
* postgresql/postgresql.c (Fpq_conn_defaults):
* postgresql/postgresql.c (Fpq_connectdb):
* postgresql/postgresql.c (Fpq_connect_start):
* postgresql/postgresql.c (Fpq_result_status):
* postgresql/postgresql.c (Fpq_res_status):
Mule-ize large parts of it.
2010-01-26 Ben Wing <ben@xemacs.org>
* ldap/eldap.c (print_ldap):
* ldap/eldap.c (allocate_ldap):
Use write_ascstring().
src/ChangeLog addition:
2010-01-26 Ben Wing <ben@xemacs.org>
* alloc.c:
* alloc.c (build_ascstring):
* alloc.c (build_msg_cistring):
* alloc.c (staticpro_1):
* alloc.c (staticpro_name):
* alloc.c (staticpro_nodump_1):
* alloc.c (staticpro_nodump_name):
* alloc.c (unstaticpro_nodump_1):
* alloc.c (mcpro_1):
* alloc.c (mcpro_name):
* alloc.c (object_memory_usage_stats):
* alloc.c (common_init_alloc_early):
* alloc.c (init_alloc_once_early):
* buffer.c (print_buffer):
* buffer.c (vars_of_buffer):
* buffer.c (common_init_complex_vars_of_buffer):
* buffer.c (init_initial_directory):
* bytecode.c (invalid_byte_code):
* bytecode.c (print_compiled_function):
* bytecode.c (mark_compiled_function):
* chartab.c (print_table_entry):
* chartab.c (print_char_table):
* config.h.in:
* console-gtk.c:
* console-gtk.c (gtk_device_to_console_connection):
* console-gtk.c (gtk_semi_canonicalize_console_connection):
* console-gtk.c (gtk_canonicalize_console_connection):
* console-gtk.c (gtk_semi_canonicalize_device_connection):
* console-gtk.c (gtk_canonicalize_device_connection):
* console-stream.c (stream_init_frame_1):
* console-stream.c (vars_of_console_stream):
* console-stream.c (init_console_stream):
* console-x.c (x_semi_canonicalize_console_connection):
* console-x.c (x_semi_canonicalize_device_connection):
* console-x.c (x_canonicalize_device_connection):
* console-x.h:
* data.c (eq_with_ebola_notice):
* data.c (Fsubr_interactive):
* data.c (Fnumber_to_string):
* data.c (digit_to_number):
* device-gtk.c (gtk_init_device):
* device-msw.c (print_devmode):
* device-x.c (x_event_name):
* dialog-msw.c (handle_directory_dialog_box):
* dialog-msw.c (handle_file_dialog_box):
* dialog-msw.c (vars_of_dialog_mswindows):
* doc.c (weird_doc):
* doc.c (Fsnarf_documentation):
* doc.c (vars_of_doc):
* dumper.c (pdump):
* dynarr.c:
* dynarr.c (Dynarr_realloc):
* editfns.c (Fuser_real_login_name):
* editfns.c (get_home_directory):
* elhash.c (print_hash_table_data):
* elhash.c (print_hash_table):
* emacs.c (main_1):
* emacs.c (vars_of_emacs):
* emodules.c:
* emodules.c (_emodules_list):
* emodules.c (Fload_module):
* emodules.c (Funload_module):
* emodules.c (Flist_modules):
* emodules.c (find_make_module):
* emodules.c (attempt_module_delete):
* emodules.c (emodules_load):
* emodules.c (emodules_doc_subr):
* emodules.c (emodules_doc_sym):
* emodules.c (syms_of_module):
* emodules.c (vars_of_module):
* emodules.h:
* eval.c (print_subr):
* eval.c (signal_call_debugger):
* eval.c (build_error_data):
* eval.c (signal_error):
* eval.c (maybe_signal_error):
* eval.c (signal_continuable_error):
* eval.c (maybe_signal_continuable_error):
* eval.c (signal_error_2):
* eval.c (maybe_signal_error_2):
* eval.c (signal_continuable_error_2):
* eval.c (maybe_signal_continuable_error_2):
* eval.c (signal_ferror):
* eval.c (maybe_signal_ferror):
* eval.c (signal_continuable_ferror):
* eval.c (maybe_signal_continuable_ferror):
* eval.c (signal_ferror_with_frob):
* eval.c (maybe_signal_ferror_with_frob):
* eval.c (signal_continuable_ferror_with_frob):
* eval.c (maybe_signal_continuable_ferror_with_frob):
* eval.c (syntax_error):
* eval.c (syntax_error_2):
* eval.c (maybe_syntax_error):
* eval.c (sferror):
* eval.c (sferror_2):
* eval.c (maybe_sferror):
* eval.c (invalid_argument):
* eval.c (invalid_argument_2):
* eval.c (maybe_invalid_argument):
* eval.c (invalid_constant):
* eval.c (invalid_constant_2):
* eval.c (maybe_invalid_constant):
* eval.c (invalid_operation):
* eval.c (invalid_operation_2):
* eval.c (maybe_invalid_operation):
* eval.c (invalid_change):
* eval.c (invalid_change_2):
* eval.c (maybe_invalid_change):
* eval.c (invalid_state):
* eval.c (invalid_state_2):
* eval.c (maybe_invalid_state):
* eval.c (wtaerror):
* eval.c (stack_overflow):
* eval.c (out_of_memory):
* eval.c (print_multiple_value):
* eval.c (issue_call_trapping_problems_warning):
* eval.c (backtrace_specials):
* eval.c (backtrace_unevalled_args):
* eval.c (Fbacktrace):
* eval.c (warn_when_safe):
* event-Xt.c (modwarn):
* event-Xt.c (modbarf):
* event-Xt.c (check_modifier):
* event-Xt.c (store_modifier):
* event-Xt.c (emacs_Xt_format_magic_event):
* event-Xt.c (describe_event):
* event-gtk.c (dragndrop_data_received):
* event-gtk.c (store_modifier):
* event-gtk.c (gtk_reset_modifier_mapping):
* event-msw.c (dde_eval_string):
* event-msw.c (Fdde_alloc_advise_item):
* event-msw.c (mswindows_dde_callback):
* event-msw.c (FROB):
* event-msw.c (emacs_mswindows_format_magic_event):
* event-stream.c (external_debugging_print_event):
* event-stream.c (execute_help_form):
* event-stream.c (vars_of_event_stream):
* events.c (print_event_1):
* events.c (print_event):
* events.c (event_equal):
* extents.c (print_extent_1):
* extents.c (print_extent):
* extents.c (vars_of_extents):
* faces.c (print_face):
* faces.c (complex_vars_of_faces):
* file-coding.c:
* file-coding.c (print_coding_system):
* file-coding.c (print_coding_system_in_print_method):
* file-coding.c (default_query_method):
* file-coding.c (find_coding_system):
* file-coding.c (make_coding_system_1):
* file-coding.c (chain_print):
* file-coding.c (undecided_print):
* file-coding.c (gzip_print):
* file-coding.c (vars_of_file_coding):
* file-coding.c (complex_vars_of_file_coding):
* fileio.c:
* fileio.c (report_file_type_error):
* fileio.c (report_error_with_errno):
* fileio.c (report_file_error):
* fileio.c (barf_or_query_if_file_exists):
* fileio.c (vars_of_fileio):
* floatfns.c (matherr):
* fns.c (print_bit_vector):
* fns.c (Fmapconcat):
* fns.c (add_suffix_to_symbol):
* fns.c (add_prefix_to_symbol):
* frame-gtk.c:
* frame-gtk.c (Fgtk_window_id):
* frame-x.c (def):
* frame-x.c (x_cde_transfer_callback):
* frame.c:
* frame.c (Fmake_frame):
* gc.c (show_gc_cursor_and_message):
* gc.c (vars_of_gc):
* glyphs-eimage.c (png_instantiate):
* glyphs-eimage.c (tiff_instantiate):
* glyphs-gtk.c (gtk_print_image_instance):
* glyphs-msw.c (mswindows_print_image_instance):
* glyphs-x.c (x_print_image_instance):
* glyphs-x.c (update_widget_face):
* glyphs.c (make_string_from_file):
* glyphs.c (print_image_instance):
* glyphs.c (signal_image_error):
* glyphs.c (signal_image_error_2):
* glyphs.c (signal_double_image_error):
* glyphs.c (signal_double_image_error_2):
* glyphs.c (xbm_mask_file_munging):
* glyphs.c (pixmap_to_lisp_data):
* glyphs.h:
* gui.c (gui_item_display_flush_left):
* hpplay.c (player_error_internal):
* hpplay.c (myHandler):
* intl-win32.c:
* intl-win32.c (langcode_to_lang):
* intl-win32.c (sublangcode_to_lang):
* intl-win32.c (Fmswindows_get_locale_info):
* intl-win32.c (lcid_to_locale_mule_or_no):
* intl-win32.c (mswindows_multibyte_to_unicode_print):
* intl-win32.c (complex_vars_of_intl_win32):
* keymap.c:
* keymap.c (print_keymap):
* keymap.c (ensure_meta_prefix_char_keymapp):
* keymap.c (Fkey_description):
* keymap.c (Ftext_char_description):
* lisp.h:
* lisp.h (struct):
* lisp.h (DECLARE_INLINE_HEADER):
* lread.c (Fload_internal):
* lread.c (locate_file):
* lread.c (read_escape):
* lread.c (read_raw_string):
* lread.c (read1):
* lread.c (read_list):
* lread.c (read_compiled_function):
* lread.c (init_lread):
* lrecord.h:
* marker.c (print_marker):
* marker.c (marker_equal):
* menubar-msw.c (displayable_menu_item):
* menubar-x.c (command_builder_operate_menu_accelerator):
* menubar.c (vars_of_menubar):
* minibuf.c (reinit_complex_vars_of_minibuf):
* minibuf.c (complex_vars_of_minibuf):
* mule-charset.c (Fmake_charset):
* mule-charset.c (complex_vars_of_mule_charset):
* mule-coding.c (iso2022_print):
* mule-coding.c (fixed_width_query):
* number.c (bignum_print):
* number.c (ratio_print):
* number.c (bigfloat_print):
* number.c (bigfloat_finalize):
* objects-msw.c:
* objects-msw.c (mswindows_color_to_string):
* objects-msw.c (mswindows_color_list):
* objects-tty.c:
* objects-tty.c (tty_font_list):
* objects-tty.c (tty_find_charset_font):
* objects-xlike-inc.c (xft_find_charset_font):
* objects-xlike-inc.c (endif):
* print.c:
* print.c (write_istring):
* print.c (write_ascstring):
* print.c (Fterpri):
* print.c (Fprint):
* print.c (print_error_message):
* print.c (print_vector_internal):
* print.c (print_cons):
* print.c (print_string):
* print.c (printing_unreadable_object):
* print.c (print_internal):
* print.c (print_float):
* print.c (print_symbol):
* process-nt.c (mswindows_report_winsock_error):
* process-nt.c (nt_canonicalize_host_name):
* process-unix.c (unix_canonicalize_host_name):
* process.c (print_process):
* process.c (report_process_error):
* process.c (report_network_error):
* process.c (make_process_internal):
* process.c (Fstart_process_internal):
* process.c (status_message):
* process.c (putenv_internal):
* process.c (vars_of_process):
* process.h:
* profile.c (vars_of_profile):
* rangetab.c (print_range_table):
* realpath.c (vars_of_realpath):
* redisplay.c (vars_of_redisplay):
* search.c (wordify):
* search.c (Freplace_match):
* sheap.c (sheap_adjust_h):
* sound.c (report_sound_error):
* sound.c (Fplay_sound_file):
* specifier.c (print_specifier):
* symbols.c (Fsubr_name):
* symbols.c (do_symval_forwarding):
* symbols.c (set_default_buffer_slot_variable):
* symbols.c (set_default_console_slot_variable):
* symbols.c (store_symval_forwarding):
* symbols.c (default_value):
* symbols.c (defsymbol_massage_name_1):
* symbols.c (defsymbol_massage_name_nodump):
* symbols.c (defsymbol_massage_name):
* symbols.c (defsymbol_massage_multiword_predicate_nodump):
* symbols.c (defsymbol_massage_multiword_predicate):
* symbols.c (defsymbol_nodump):
* symbols.c (defsymbol):
* symbols.c (defkeyword):
* symbols.c (defkeyword_massage_name):
* symbols.c (check_module_subr):
* symbols.c (deferror_1):
* symbols.c (deferror):
* symbols.c (deferror_massage_name):
* symbols.c (deferror_massage_name_and_message):
* symbols.c (defvar_magic):
* symeval.h:
* symeval.h (DEFVAR_SYMVAL_FWD):
* sysdep.c:
* sysdep.c (init_system_name):
* sysdll.c:
* sysdll.c (MAYBE_PREPEND_UNDERSCORE):
* sysdll.c (dll_function):
* sysdll.c (dll_variable):
* sysdll.c (dll_error):
* sysdll.c (dll_open):
* sysdll.c (dll_close):
* sysdll.c (image_for_address):
* sysdll.c (my_find_image):
* sysdll.c (search_linked_libs):
* sysdll.h:
* sysfile.h:
* sysfile.h (DEFAULT_DIRECTORY_FALLBACK):
* syswindows.h:
* tests.c (DFC_CHECK_LENGTH):
* tests.c (DFC_CHECK_CONTENT):
* tests.c (Ftest_hash_tables):
* text.c (vars_of_text):
* text.h:
* tooltalk.c (tt_opnum_string):
* tooltalk.c (tt_message_arg_ival_string):
* tooltalk.c (Ftooltalk_default_procid):
* tooltalk.c (Ftooltalk_default_session):
* tooltalk.c (init_tooltalk):
* tooltalk.c (vars_of_tooltalk):
* ui-gtk.c (Fdll_load):
* ui-gtk.c (type_to_marshaller_type):
* ui-gtk.c (Fgtk_import_function_internal):
* ui-gtk.c (emacs_gtk_object_printer):
* ui-gtk.c (emacs_gtk_boxed_printer):
* unicode.c (unicode_to_ichar):
* unicode.c (unicode_print):
* unicode.c (unicode_query):
* unicode.c (vars_of_unicode):
* unicode.c (complex_vars_of_unicode):
* win32.c:
* win32.c (mswindows_report_process_error):
* window.c (print_window):
* xemacs.def.in.in:
BASIC IDEA: Further fixing up uses of char * and CIbyte *
to reflect their actual semantics; Mule-izing some code;
redoing of the not-yet-working code to handle message translation.
Clean up code to handle message-translation (not yet working).
Create separate versions of build_msg_string() for working with
Ibyte *, CIbyte *, and Ascbyte * arguments. Assert that Ascbyte *
arguments are pure-ASCII. Make build_msg_string() be the same
as build_msg_ascstring(). Create same three versions of GETTEXT()
and DEFER_GETTEXT(). Also create build_defer_string() and
variants for the equivalent of DEFER_GETTEXT() when building a
string. Remove old CGETTEXT(). Clean up code where GETTEXT(),
DEFER_GETTEXT(), build_msg_string(), etc. was being called and
introduce some new calls to build_msg_string(), etc. Remove
GETTEXT() from calls to weird_doc() -- we assume that the
message snarfer knows about weird_doc(). Remove uses of
DEFER_GETTEXT() from error messages in sysdep.c and instead use
special comments /* @@@begin-snarf@@@ */ and /* @@@end-snarf@@@ */
that the message snarfer presumably knows about.
Create build_ascstring() and use it in many instances in place
of build_string(). The purpose of having Ascbyte * variants is
to make the code more self-documenting in terms of what sort of
semantics is expected for char * strings. In fact in the process
of looking for uses of build_string(), much improperly Mule-ized
was discovered.
Mule-ize a lot of code as described in previous paragraph,
e.g. in sysdep.c.
Make the error functions take Ascbyte * strings and fix up a
couple of places where non-pure-ASCII strings were being passed in
(file-coding.c, mule-coding.c, unicode.c). (It's debatable whether
we really need to make the error functions work this way. It
helps catch places where code is written in a way that message
translation won't work, but we may well never implement message
translation.)
Make staticpro() and friends take Ascbyte * strings instead of
raw char * strings. Create a const_Ascbyte_ptr dynarr type
to describe what's held by staticpro_names[] and friends,
create pdump descriptions for const_Ascbyte_ptr dynarrs, and
use them in place of specially-crafted staticpro descriptions.
Mule-ize certain other functions (e.g. x_event_name) by correcting
raw use of char * to Ascbyte *, Rawbyte * or another such type,
and raw use of char[] buffers to another type (usually Ascbyte[]).
Change many uses of write_c_string() to write_msg_string(),
write_ascstring(), etc.
Mule-ize emodules.c, emodules.h, sysdll.h.
Fix some un-Mule-ized code in intl-win32.c.
A comment in event-Xt.c and the limitations of the message
snarfer (make-msgfile or whatever) is presumably incorrect --
it should be smart enough to handle function calls spread over
more than one line. Clean up code in event-Xt.c that was
written awkwardly for this reason.
In config.h.in, instead of NEED_ERROR_CHECK_TYPES_INLINES,
create a more general XEMACS_DEFS_NEEDS_INLINE_DECLS to
indicate when inlined functions need to be declared in
xemacs.defs.in.in, and make use of it in xemacs.defs.in.in.
We need to do this because postgresql.c now calls qxestrdup(),
which is an inline function.
Make nconc2() and other such functions MODULE_API and put
them in xemacs.defs.in.in since postgresql.c now uses them.
Clean up indentation in lread.c and a few other places.
In text.h, document ASSERT_ASCTEXT_ASCII() and
ASSERT_ASCTEXT_ASCII_LEN(), group together the stand-in
encodings and add some more for DLL symbols, function and
variable names, etc.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Tue, 26 Jan 2010 23:22:30 -0600 |
| parents | 95b25f4e7340 |
| children |
| rev | line source |
|---|---|
| 428 | 1 \input texinfo.tex |
| 2 | |
| 3 @c %**start of header | |
| 4 @setfilename ../info/custom.info | |
| 5 @settitle The Customization Library | |
| 6 @iftex | |
| 7 @afourpaper | |
| 8 @headings double | |
| 9 @end iftex | |
| 10 @c %**end of header | |
| 11 | |
| 12 @ifinfo | |
| 13 @dircategory XEmacs Editor | |
| 14 @direntry | |
| 15 * Customizations: (custom). Customization Library. | |
| 16 @end direntry | |
| 17 @end ifinfo | |
| 18 | |
| 19 @node Top, Declaring Groups, (dir), (dir) | |
| 20 @comment node-name, next, previous, up | |
| 21 @top The Customization Library | |
| 22 | |
| 23 This manual describes how to declare customization groups, variables, | |
| 24 and faces. It doesn't contain any examples, but please look at the file | |
| 25 @file{cus-edit.el} which contains many declarations you can learn from. | |
| 26 | |
| 27 @menu | |
| 28 * Declaring Groups:: | |
| 29 * Declaring Variables:: | |
| 30 * Declaring Faces:: | |
| 31 * Usage for Package Authors:: | |
| 32 * Utilities:: | |
| 33 * The Init File:: | |
| 34 * Wishlist:: | |
| 35 @end menu | |
| 36 | |
| 37 All the customization declarations can be changes by keyword arguments. | |
| 38 Groups, variables, and faces all share these common keywords: | |
| 39 | |
| 40 @table @code | |
| 41 @item :group | |
| 42 @var{value} should be a customization group. | |
| 43 Add @var{symbol} to that group. | |
| 44 @item :link | |
| 45 @var{value} should be a widget type. | |
| 46 Add @var{value} to the external links for this customization option. | |
| 47 Useful widget types include @code{custom-manual}, @code{info-link}, and | |
| 48 @code{url-link}. | |
| 49 @item :load | |
| 50 Add @var{value} to the files that should be loaded before displaying | |
| 51 this customization option. The value should be either a string, which | |
| 52 should be a string which will be loaded with @code{load-library} unless | |
| 53 present in @code{load-history}, or a symbol which will be loaded with | |
| 54 @code{require}. | |
| 55 @item :tag | |
| 56 @var{Value} should be a short string used for identifying the option in | |
| 57 customization menus and buffers. By default the tag will be | |
| 58 automatically created from the options name. | |
| 59 @end table | |
| 60 | |
| 61 @node Declaring Groups, Declaring Variables, Top, Top | |
| 62 @comment node-name, next, previous, up | |
| 63 @section Declaring Groups | |
| 64 | |
| 65 Use @code{defgroup} to declare new customization groups. | |
| 66 | |
| 67 @defun defgroup symbol members doc [keyword value]... | |
| 68 Declare @var{symbol} as a customization group containing @var{members}. | |
| 69 @var{symbol} does not need to be quoted. | |
| 70 | |
| 71 @var{doc} is the group documentation. | |
| 72 | |
| 73 @var{members} should be an alist of the form ((@var{name} | |
| 74 @var{widget})...) where @var{name} is a symbol and @var{widget} is a | |
| 75 widget for editing that symbol. Useful widgets are | |
| 76 @code{custom-variable} for editing variables, @code{custom-face} for | |
| 77 editing faces, and @code{custom-group} for editing groups.@refill | |
| 78 | |
| 79 Internally, custom uses the symbol property @code{custom-group} to keep | |
| 80 track of the group members, and @code{group-documentation} for the | |
| 81 documentation string. | |
| 82 | |
| 83 The following additional @var{keyword}'s are defined: | |
| 84 | |
| 85 @table @code | |
| 86 @item :prefix | |
| 87 @var{value} should be a string. If the string is a prefix for the name | |
| 88 of a member of the group, that prefix will be ignored when creating a | |
| 89 tag for that member. | |
| 90 @end table | |
| 91 @end defun | |
| 92 | |
| 93 @node Declaring Variables, Declaring Faces, Declaring Groups, Top | |
| 94 @comment node-name, next, previous, up | |
| 95 @section Declaring Variables | |
| 96 | |
| 97 Use @code{defcustom} to declare user editable variables. | |
| 98 | |
| 99 @defun defcustom symbol value doc [keyword value]... | |
| 100 Declare @var{symbol} as a customizable variable that defaults to @var{value}. | |
| 101 Neither @var{symbol} nor @var{value} needs to be quoted. | |
| 102 If @var{symbol} is not already bound, initialize it to @var{value}. | |
| 103 | |
| 104 @var{doc} is the variable documentation. | |
| 105 | |
| 106 The following additional @var{keyword}'s are defined: | |
| 107 | |
| 108 @table @code | |
| 109 @item :type | |
| 110 @var{value} should be a widget type. | |
| 111 | |
| 112 @item :options | |
| 113 @var{value} should be a list of possible members of the specified type. | |
| 114 For hooks, this is a list of function names. | |
| 115 | |
| 116 @item :initialize | |
| 117 @var{value} should be a function used to initialize the variable. It | |
| 118 takes two arguments, the symbol and value given in the @code{defcustom} call. | |
| 119 Some predefined functions are: | |
| 120 | |
| 121 @table @code | |
| 122 @item custom-initialize-set | |
| 123 Use the @code{:set} method to initialize the variable. Do not | |
| 124 initialize it if already bound. This is the default @code{:initialize} | |
| 125 method. | |
| 126 | |
| 127 @item custom-initialize-default | |
| 128 Always use @code{set-default} to initialize the variable, even if a | |
| 129 @code{:set} method has been specified. | |
| 130 | |
| 131 @item custom-initialize-reset | |
| 132 If the variable is already bound, reset it by calling the @code{:set} | |
| 133 method with the value returned by the @code{:get} method. | |
| 134 | |
| 135 @item custom-initialize-changed | |
| 136 Like @code{custom-initialize-reset}, but use @code{set-default} to | |
| 137 initialize the variable if it is not bound and has not been set | |
| 138 already. | |
| 139 @end table | |
| 140 | |
| 141 @item :set | |
| 142 @var{value} should be a function to set the value of the symbol. It | |
| 143 takes two arguments, the symbol to set and the value to give it. The | |
| 144 default is @code{set-default}. | |
| 145 | |
| 146 @item :get | |
| 147 @var{value} should be a function to extract the value of symbol. The | |
| 148 function takes one argument, a symbol, and should return the current | |
| 149 value for that symbol. The default is @code{default-value}. | |
| 150 | |
| 151 @item :require | |
| 152 @var{value} should be a feature symbol. Each feature will be required | |
| 153 when the `defcustom' is evaluated, or when Emacs is started if the user | |
| 154 has saved this option. | |
| 155 | |
| 156 @end table | |
| 157 | |
| 158 @xref{Sexp Types,,,widget,The Widget Library}, for information about | |
| 159 widgets to use together with the @code{:type} keyword. | |
| 160 @end defun | |
| 161 | |
| 162 Internally, custom uses the symbol property @code{custom-type} to keep | |
| 163 track of the variables type, @code{standard-value} for the program | |
| 164 specified default value, @code{saved-value} for a value saved by the | |
| 165 user, and @code{variable-documentation} for the documentation string. | |
| 166 | |
| 167 Use @code{custom-add-option} to specify that a specific function is | |
| 3128 | 168 useful as a member of a hook. |
| 428 | 169 |
| 170 @defun custom-add-option symbol option | |
| 171 To the variable @var{symbol} add @var{option}. | |
| 172 | |
| 173 If @var{symbol} is a hook variable, @var{option} should be a hook | |
| 3128 | 174 member. For other types of variables, the effect is undefined." |
| 428 | 175 @end defun |
| 176 | |
| 177 @node Declaring Faces, Usage for Package Authors, Declaring Variables, Top | |
| 178 @comment node-name, next, previous, up | |
| 179 @section Declaring Faces | |
| 180 | |
| 181 Faces are declared with @code{defface}. | |
| 182 | |
| 183 @defun defface face spec doc [keyword value]... | |
| 184 | |
| 185 Declare @var{face} as a customizable face that defaults to @var{spec}. | |
| 186 @var{face} does not need to be quoted. | |
| 187 | |
| 188 If @var{face} has been set with `custom-set-face', set the face attributes | |
| 189 as specified by that function, otherwise set the face attributes | |
| 190 according to @var{spec}. | |
| 191 | |
| 192 @var{doc} is the face documentation. | |
| 193 | |
| 194 @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}. | |
| 195 | |
| 196 @var{atts} is a list of face attributes and their values. The possible | |
| 197 attributes are defined in the variable `custom-face-attributes'. | |
| 198 | |
| 199 The @var{atts} of the first entry in @var{spec} where the @var{display} | |
| 200 matches the frame should take effect in that frame. @var{display} can | |
| 201 either be the symbol `t', which will match all frames, or an alist of | |
| 202 the form @samp{((@var{req} @var{item}...)...)}@refill | |
| 203 | |
| 204 For the @var{display} to match a FRAME, the @var{req} property of the | |
| 205 frame must match one of the @var{item}. The following @var{req} are | |
| 206 defined:@refill | |
| 207 | |
| 208 @table @code | |
| 209 @item type | |
| 210 (the value of (window-system))@* | |
| 211 Should be one of @code{x} or @code{tty}. | |
| 212 | |
| 213 @item class | |
| 214 (the frame's color support)@* | |
| 215 Should be one of @code{color}, @code{grayscale}, or @code{mono}. | |
| 216 | |
| 217 @item background | |
| 218 (what color is used for the background text)@* | |
| 219 Should be one of @code{light} or @code{dark}. | |
| 220 @end table | |
| 221 | |
| 222 Internally, custom uses the symbol property @code{face-defface-spec} for | |
| 223 the program specified default face properties, @code{saved-face} for | |
| 224 properties saved by the user, and @code{face-documentation} for the | |
| 225 documentation string.@refill | |
| 226 | |
| 227 @end defun | |
| 228 | |
| 229 @node Usage for Package Authors, Utilities, Declaring Faces, Top | |
| 230 @comment node-name, next, previous, up | |
| 231 @section Usage for Package Authors | |
| 232 | |
| 233 The recommended usage for the author of a typical emacs lisp package is | |
| 234 to create one group identifying the package, and make all user options | |
| 235 and faces members of that group. If the package has more than around 20 | |
| 236 such options, they should be divided into a number of subgroups, with | |
| 237 each subgroup being member of the top level group. | |
| 238 | |
| 239 The top level group for the package should itself be member of one or | |
| 240 more of the standard customization groups. There exists a group for | |
| 241 each @emph{finder} keyword. Press @kbd{C-h p} to see a list of finder | |
| 242 keywords, and add you group to each of them, using the @code{:group} | |
| 243 keyword. | |
| 244 | |
| 245 @node Utilities, The Init File, Usage for Package Authors, Top | |
| 246 @comment node-name, next, previous, up | |
| 247 @section Utilities | |
| 248 | |
| 249 These utilities can come in handy when adding customization support. | |
| 250 | |
| 251 @deffn Widget custom-manual | |
| 252 Widget type for specifying the info manual entry for a customization | |
| 253 option. It takes one argument, an info address. | |
| 254 @end deffn | |
| 255 | |
| 256 @defun custom-add-to-group group member widget | |
| 257 To existing @var{group} add a new @var{member} of type @var{widget}, | |
| 258 If there already is an entry for that member, overwrite it. | |
| 259 @end defun | |
| 260 | |
| 261 @defun custom-add-link symbol widget | |
| 262 To the custom option @var{symbol} add the link @var{widget}. | |
| 263 @end defun | |
| 264 | |
| 265 @defun custom-add-load symbol load | |
| 266 To the custom option @var{symbol} add the dependency @var{load}. | |
| 267 @var{load} should be either a library file name, or a feature name. | |
| 268 @end defun | |
| 269 | |
| 270 @defun customize-menu-create symbol &optional name | |
| 271 Create menu for customization group @var{symbol}. | |
| 272 If optional @var{name} is given, use that as the name of the menu. | |
| 273 Otherwise the menu will be named `Customize'. | |
| 274 The menu is in a format applicable to @code{easy-menu-define}. | |
| 275 @end defun | |
| 276 | |
| 277 @node The Init File, Wishlist, Utilities, Top | |
| 278 @comment node-name, next, previous, up | |
| 279 @section The Init File | |
| 280 | |
| 863 | 281 Customizations are saved to the file specified by @code{custom-file}, as |
| 282 calls to @code{custom-set-variables} and @code{custom-set-faces}. | |
| 283 | |
| 284 When you save customizations, the current implementation removes the | |
| 285 calls to @code{custom-set-variables} and @code{custom-set-faces}, and | |
| 286 replaces them with code generated on the basis of the current | |
| 287 customization state in Emacs. | |
| 288 | |
| 289 By default @code{custom-file} is your @file{.emacs} file (for GNU Emacs | |
| 290 and older XEmacs) and is @file{custom.el} in the same directory as | |
| 291 @file{init.el} (in XEmacs 21.4 and later). If you use another file, you | |
| 292 must explicitly load it yourself. | |
| 293 | |
| 1738 | 294 As of XEmacs 21.4.7, when @code{custom-file} is present, it is loaded |
| 863 | 295 @emph{after} @file{init.el}. This is likely to change in the future, |
| 296 because (1) actions in @file{init.el} often would like to depend on | |
| 297 customizations for consistent appearance and (2) Custom is quite brutal | |
| 298 about enforcing its idea of the correct values at initialization. | |
| 428 | 299 |
| 300 @node Wishlist, , The Init File, Top | |
| 301 @comment node-name, next, previous, up | |
| 302 @section Wishlist | |
| 303 | |
| 304 @itemize @bullet | |
| 305 @item | |
| 306 Better support for keyboard operations in the customize buffer. | |
| 307 | |
| 308 @item | |
| 309 Integrate with @file{w3} so you can get customization buffers with much | |
| 310 better formatting. I'm thinking about adding a <custom>name</custom> | |
| 311 tag. The latest w3 have some support for this, so come up with a | |
| 312 convincing example. | |
| 313 | |
| 314 @item | |
| 315 Add an `examples' section, with explained examples of custom type | |
| 316 definitions. | |
| 317 | |
| 318 @item | |
| 319 Support selectable color themes. I.e., change many faces by setting one | |
| 320 variable. | |
| 321 | |
| 322 @item | |
| 323 Support undo using lmi's @file{gnus-undo.el}. | |
| 324 | |
| 325 | |
| 326 @item | |
| 327 Make it possible to append to `choice', `radio', and `set' options. | |
| 328 | |
| 329 @item | |
| 330 Ask whether set or modified variables should be saved in | |
| 331 @code{kill-buffer-hook}. | |
| 332 | |
| 333 Ditto for @code{kill-emacs-query-functions}. | |
| 334 | |
| 335 @item | |
| 336 Command to check if there are any customization options that | |
| 337 does not belong to an existing group. | |
| 338 | |
| 339 @item | |
| 340 Optionally disable the point-cursor and instead highlight the selected | |
| 341 item in XEmacs. This is like the *Completions* buffer in XEmacs. | |
| 342 Suggested by Jens Lautenbacher | |
| 343 @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill | |
| 344 | |
| 345 @item | |
| 346 Explain why it is necessary that all choices have different default | |
| 347 values. | |
| 348 | |
| 349 @item | |
| 350 Add some direct support for meta variables, i.e. make it possible to | |
| 351 specify that this variable should be reset when that variable is | |
| 352 changed. | |
| 353 | |
| 354 @item | |
| 355 Add tutorial. | |
| 356 | |
| 357 @item | |
| 358 Describe the @code{:type} syntax in this manual. | |
| 359 | |
| 360 @item | |
| 361 Find a place is this manual for the following text: | |
| 362 | |
| 363 @strong{Radio vs. Buttons} | |
| 364 | |
| 365 Use a radio if you can't find a good way to describe the item in the | |
| 366 choice menu text. I.e. it is better to use a radio if you expect the | |
| 367 user would otherwise manually select each item from the choice menu in | |
| 368 turn to see what it expands too. | |
| 369 | |
| 370 Avoid radios if some of the items expands to complex structures. | |
| 371 | |
| 372 I mostly use radios when most of the items are of type | |
| 373 @code{function-item} or @code{variable-item}. | |
| 374 | |
| 375 @item | |
| 376 Update customize buffers when @code{custom-set-variable} or | |
| 377 @code{custom-save-customized} is called. | |
| 378 | |
| 379 @item | |
| 380 Better handling of saved but uninitialized items. | |
| 381 | |
| 382 @item | |
| 383 Detect when faces have been changed outside customize. | |
| 384 | |
| 385 @item | |
| 386 Enable mouse help in Emacs by default. | |
| 387 | |
| 388 @item | |
| 389 Add an easy way to display the standard settings when an item is modified. | |
| 390 | |
| 391 @item | |
| 392 See if it is feasible to scan files for customization information | |
| 393 instead of loading them, | |
| 394 | |
| 395 @item | |
| 396 Add hint message when user push a non-pushable tag. | |
| 397 | |
| 398 Suggest that the user unhide if hidden, and edit the value directly | |
| 399 otherwise. | |
| 400 | |
| 401 @item | |
| 402 Use checkboxes and radio buttons in the state menus. | |
| 403 | |
| 404 @item | |
| 405 Add option to hide @samp{[hide]} for short options. Default, on. | |
| 406 | |
| 407 @item | |
| 408 Add option to hide @samp{[state]} for options with their standard | |
| 409 settings. | |
| 410 | |
| 411 @item | |
| 412 There should be a way to specify site defaults for user options. | |
| 413 | |
| 414 @item | |
| 415 There should be more buffer styles. The default `nested style, the old | |
| 416 `outline' style, a `numeric' style with numbers instead of stars, an | |
| 417 `empty' style with just the group name, and `compact' with only one line | |
| 418 per item. | |
| 419 | |
| 420 @item | |
| 421 Newline and tab should be displayed as @samp{^J} and @samp{^I} in the | |
| 422 @code{regexp} and @code{file} widgets. I think this can be done in | |
| 423 XEmacs by adding a display table to the face. | |
| 424 | |
| 425 @item | |
| 426 Use glyphs to draw the @code{customize-browse} tree. | |
| 427 | |
| 428 Add echo and balloon help. You should be able to read the documentation | |
| 429 simply by moving the mouse pointer above the name. | |
| 430 | |
| 431 Add parent links. | |
| 432 | |
| 433 Add colors. | |
| 434 | |
| 435 @end itemize | |
| 436 | |
| 437 @contents | |
| 438 @bye |