Mercurial > hg > xemacs-beta
view 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 |
line wrap: on
line source
\input texinfo.tex @c %**start of header @setfilename ../info/custom.info @settitle The Customization Library @iftex @afourpaper @headings double @end iftex @c %**end of header @ifinfo @dircategory XEmacs Editor @direntry * Customizations: (custom). Customization Library. @end direntry @end ifinfo @node Top, Declaring Groups, (dir), (dir) @comment node-name, next, previous, up @top The Customization Library This manual describes how to declare customization groups, variables, and faces. It doesn't contain any examples, but please look at the file @file{cus-edit.el} which contains many declarations you can learn from. @menu * Declaring Groups:: * Declaring Variables:: * Declaring Faces:: * Usage for Package Authors:: * Utilities:: * The Init File:: * Wishlist:: @end menu All the customization declarations can be changes by keyword arguments. Groups, variables, and faces all share these common keywords: @table @code @item :group @var{value} should be a customization group. Add @var{symbol} to that group. @item :link @var{value} should be a widget type. Add @var{value} to the external links for this customization option. Useful widget types include @code{custom-manual}, @code{info-link}, and @code{url-link}. @item :load Add @var{value} to the files that should be loaded before displaying this customization option. The value should be either a string, which should be a string which will be loaded with @code{load-library} unless present in @code{load-history}, or a symbol which will be loaded with @code{require}. @item :tag @var{Value} should be a short string used for identifying the option in customization menus and buffers. By default the tag will be automatically created from the options name. @end table @node Declaring Groups, Declaring Variables, Top, Top @comment node-name, next, previous, up @section Declaring Groups Use @code{defgroup} to declare new customization groups. @defun defgroup symbol members doc [keyword value]... Declare @var{symbol} as a customization group containing @var{members}. @var{symbol} does not need to be quoted. @var{doc} is the group documentation. @var{members} should be an alist of the form ((@var{name} @var{widget})...) where @var{name} is a symbol and @var{widget} is a widget for editing that symbol. Useful widgets are @code{custom-variable} for editing variables, @code{custom-face} for editing faces, and @code{custom-group} for editing groups.@refill Internally, custom uses the symbol property @code{custom-group} to keep track of the group members, and @code{group-documentation} for the documentation string. The following additional @var{keyword}'s are defined: @table @code @item :prefix @var{value} should be a string. If the string is a prefix for the name of a member of the group, that prefix will be ignored when creating a tag for that member. @end table @end defun @node Declaring Variables, Declaring Faces, Declaring Groups, Top @comment node-name, next, previous, up @section Declaring Variables Use @code{defcustom} to declare user editable variables. @defun defcustom symbol value doc [keyword value]... Declare @var{symbol} as a customizable variable that defaults to @var{value}. Neither @var{symbol} nor @var{value} needs to be quoted. If @var{symbol} is not already bound, initialize it to @var{value}. @var{doc} is the variable documentation. The following additional @var{keyword}'s are defined: @table @code @item :type @var{value} should be a widget type. @item :options @var{value} should be a list of possible members of the specified type. For hooks, this is a list of function names. @item :initialize @var{value} should be a function used to initialize the variable. It takes two arguments, the symbol and value given in the @code{defcustom} call. Some predefined functions are: @table @code @item custom-initialize-set Use the @code{:set} method to initialize the variable. Do not initialize it if already bound. This is the default @code{:initialize} method. @item custom-initialize-default Always use @code{set-default} to initialize the variable, even if a @code{:set} method has been specified. @item custom-initialize-reset If the variable is already bound, reset it by calling the @code{:set} method with the value returned by the @code{:get} method. @item custom-initialize-changed Like @code{custom-initialize-reset}, but use @code{set-default} to initialize the variable if it is not bound and has not been set already. @end table @item :set @var{value} should be a function to set the value of the symbol. It takes two arguments, the symbol to set and the value to give it. The default is @code{set-default}. @item :get @var{value} should be a function to extract the value of symbol. The function takes one argument, a symbol, and should return the current value for that symbol. The default is @code{default-value}. @item :require @var{value} should be a feature symbol. Each feature will be required when the `defcustom' is evaluated, or when Emacs is started if the user has saved this option. @end table @xref{Sexp Types,,,widget,The Widget Library}, for information about widgets to use together with the @code{:type} keyword. @end defun Internally, custom uses the symbol property @code{custom-type} to keep track of the variables type, @code{standard-value} for the program specified default value, @code{saved-value} for a value saved by the user, and @code{variable-documentation} for the documentation string. Use @code{custom-add-option} to specify that a specific function is useful as a member of a hook. @defun custom-add-option symbol option To the variable @var{symbol} add @var{option}. If @var{symbol} is a hook variable, @var{option} should be a hook member. For other types of variables, the effect is undefined." @end defun @node Declaring Faces, Usage for Package Authors, Declaring Variables, Top @comment node-name, next, previous, up @section Declaring Faces Faces are declared with @code{defface}. @defun defface face spec doc [keyword value]... Declare @var{face} as a customizable face that defaults to @var{spec}. @var{face} does not need to be quoted. If @var{face} has been set with `custom-set-face', set the face attributes as specified by that function, otherwise set the face attributes according to @var{spec}. @var{doc} is the face documentation. @var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}. @var{atts} is a list of face attributes and their values. The possible attributes are defined in the variable `custom-face-attributes'. The @var{atts} of the first entry in @var{spec} where the @var{display} matches the frame should take effect in that frame. @var{display} can either be the symbol `t', which will match all frames, or an alist of the form @samp{((@var{req} @var{item}...)...)}@refill For the @var{display} to match a FRAME, the @var{req} property of the frame must match one of the @var{item}. The following @var{req} are defined:@refill @table @code @item type (the value of (window-system))@* Should be one of @code{x} or @code{tty}. @item class (the frame's color support)@* Should be one of @code{color}, @code{grayscale}, or @code{mono}. @item background (what color is used for the background text)@* Should be one of @code{light} or @code{dark}. @end table Internally, custom uses the symbol property @code{face-defface-spec} for the program specified default face properties, @code{saved-face} for properties saved by the user, and @code{face-documentation} for the documentation string.@refill @end defun @node Usage for Package Authors, Utilities, Declaring Faces, Top @comment node-name, next, previous, up @section Usage for Package Authors The recommended usage for the author of a typical emacs lisp package is to create one group identifying the package, and make all user options and faces members of that group. If the package has more than around 20 such options, they should be divided into a number of subgroups, with each subgroup being member of the top level group. The top level group for the package should itself be member of one or more of the standard customization groups. There exists a group for each @emph{finder} keyword. Press @kbd{C-h p} to see a list of finder keywords, and add you group to each of them, using the @code{:group} keyword. @node Utilities, The Init File, Usage for Package Authors, Top @comment node-name, next, previous, up @section Utilities These utilities can come in handy when adding customization support. @deffn Widget custom-manual Widget type for specifying the info manual entry for a customization option. It takes one argument, an info address. @end deffn @defun custom-add-to-group group member widget To existing @var{group} add a new @var{member} of type @var{widget}, If there already is an entry for that member, overwrite it. @end defun @defun custom-add-link symbol widget To the custom option @var{symbol} add the link @var{widget}. @end defun @defun custom-add-load symbol load To the custom option @var{symbol} add the dependency @var{load}. @var{load} should be either a library file name, or a feature name. @end defun @defun customize-menu-create symbol &optional name Create menu for customization group @var{symbol}. If optional @var{name} is given, use that as the name of the menu. Otherwise the menu will be named `Customize'. The menu is in a format applicable to @code{easy-menu-define}. @end defun @node The Init File, Wishlist, Utilities, Top @comment node-name, next, previous, up @section The Init File Customizations are saved to the file specified by @code{custom-file}, as calls to @code{custom-set-variables} and @code{custom-set-faces}. When you save customizations, the current implementation removes the calls to @code{custom-set-variables} and @code{custom-set-faces}, and replaces them with code generated on the basis of the current customization state in Emacs. By default @code{custom-file} is your @file{.emacs} file (for GNU Emacs and older XEmacs) and is @file{custom.el} in the same directory as @file{init.el} (in XEmacs 21.4 and later). If you use another file, you must explicitly load it yourself. As of XEmacs 21.4.7, when @code{custom-file} is present, it is loaded @emph{after} @file{init.el}. This is likely to change in the future, because (1) actions in @file{init.el} often would like to depend on customizations for consistent appearance and (2) Custom is quite brutal about enforcing its idea of the correct values at initialization. @node Wishlist, , The Init File, Top @comment node-name, next, previous, up @section Wishlist @itemize @bullet @item Better support for keyboard operations in the customize buffer. @item Integrate with @file{w3} so you can get customization buffers with much better formatting. I'm thinking about adding a <custom>name</custom> tag. The latest w3 have some support for this, so come up with a convincing example. @item Add an `examples' section, with explained examples of custom type definitions. @item Support selectable color themes. I.e., change many faces by setting one variable. @item Support undo using lmi's @file{gnus-undo.el}. @item Make it possible to append to `choice', `radio', and `set' options. @item Ask whether set or modified variables should be saved in @code{kill-buffer-hook}. Ditto for @code{kill-emacs-query-functions}. @item Command to check if there are any customization options that does not belong to an existing group. @item Optionally disable the point-cursor and instead highlight the selected item in XEmacs. This is like the *Completions* buffer in XEmacs. Suggested by Jens Lautenbacher @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill @item Explain why it is necessary that all choices have different default values. @item Add some direct support for meta variables, i.e. make it possible to specify that this variable should be reset when that variable is changed. @item Add tutorial. @item Describe the @code{:type} syntax in this manual. @item Find a place is this manual for the following text: @strong{Radio vs. Buttons} Use a radio if you can't find a good way to describe the item in the choice menu text. I.e. it is better to use a radio if you expect the user would otherwise manually select each item from the choice menu in turn to see what it expands too. Avoid radios if some of the items expands to complex structures. I mostly use radios when most of the items are of type @code{function-item} or @code{variable-item}. @item Update customize buffers when @code{custom-set-variable} or @code{custom-save-customized} is called. @item Better handling of saved but uninitialized items. @item Detect when faces have been changed outside customize. @item Enable mouse help in Emacs by default. @item Add an easy way to display the standard settings when an item is modified. @item See if it is feasible to scan files for customization information instead of loading them, @item Add hint message when user push a non-pushable tag. Suggest that the user unhide if hidden, and edit the value directly otherwise. @item Use checkboxes and radio buttons in the state menus. @item Add option to hide @samp{[hide]} for short options. Default, on. @item Add option to hide @samp{[state]} for options with their standard settings. @item There should be a way to specify site defaults for user options. @item There should be more buffer styles. The default `nested style, the old `outline' style, a `numeric' style with numbers instead of stars, an `empty' style with just the group name, and `compact' with only one line per item. @item Newline and tab should be displayed as @samp{^J} and @samp{^I} in the @code{regexp} and @code{file} widgets. I think this can be done in XEmacs by adding a display table to the face. @item Use glyphs to draw the @code{customize-browse} tree. Add echo and balloon help. You should be able to read the documentation simply by moving the mouse pointer above the name. Add parent links. Add colors. @end itemize @contents @bye