diff options
author | Ernestas Kulik <ernestask@gnome.org> | 2017-03-22 14:31:51 +0200 |
---|---|---|
committer | Ernestas Kulik <ernestask@gnome.org> | 2017-03-22 17:18:29 +0200 |
commit | 033378c418b32af5280f855b206a34bf0a3e148a (patch) | |
tree | f101acbe7c9561560b1d2df6531e6774758eb957 | |
parent | 64f16e19c0dea88e9a992122904d104ecca8b954 (diff) | |
download | nautilus-033378c418b32af5280f855b206a34bf0a3e148a.tar.gz |
docs: remove outdated documentation
Most documentation is outdated and/or incomplete with no maintainers.
This commit removes it.
https://bugzilla.gnome.org/show_bug.cgi?id=780366
-rw-r--r-- | docs/architecture.txt | 160 | ||||
-rw-r--r-- | docs/dnd.txt | 92 | ||||
-rw-r--r-- | docs/key_mouse_navigation.txt | 112 | ||||
-rw-r--r-- | docs/load-states.dia | bin | 2026 -> 0 bytes | |||
-rw-r--r-- | docs/nautilus-internals.pdf | bin | 307912 -> 0 bytes | |||
-rw-r--r-- | docs/nautilus-internals.sxw | bin | 59286 -> 0 bytes | |||
-rw-r--r-- | docs/nautilus-io.txt | 255 | ||||
-rw-r--r-- | docs/nautilus.faq | 7 | ||||
-rw-r--r-- | docs/recommended-books.html | 167 | ||||
-rw-r--r-- | docs/smoketests.html | 555 | ||||
-rw-r--r-- | docs/state-machines.txt | 77 | ||||
-rw-r--r-- | docs/style-guide.html | 137 |
12 files changed, 0 insertions, 1562 deletions
diff --git a/docs/architecture.txt b/docs/architecture.txt deleted file mode 100644 index 76a5bb74f..000000000 --- a/docs/architecture.txt +++ /dev/null @@ -1,160 +0,0 @@ - - -* Nautilus Architecture Block Diagram - - -+-----------------------------------------------------------------------+ -| | -| nautilus application | -| | -| +----------------------------------------------------------+ | -| | | | -| | | | -| | NautilusWindow | | -| | | | -| | | | -| +----------------------------------------------------------+ | -| | | | | -| | | | | -| \|/ \|/ \|/ | -| +---------------------+ +------------------+ +------------------+ | -| | | | | | | | -| | NautilusContentView | | NautilusMetaView | | NautilusMetaView | | -| | | | | | | | -| +---------------------+ +------------------+ +------------------+ | -| /||\ /||\ /||\ | -| || || || | -+----------||---------------------------||------------------------||----+ - || || || - CORBA CORBA CORBA - || || || -+----------||------------------+ +------||-------------------+ +--||-----------------------+ -| \||/ | | \||/ | | \||/ | -| +--------------------------+ | | +-----------------------+ | | +-----------------------+ | -| | | | | | | | | | | | -| | NautilusContentViewFrame | | | | NautilusMetaViewFrame | | | | NautilusMetaViewFrame | | -| | | | | | | | | | | | -| +--------------------------+ | | +-----------------------+ | | +-----------------------+ | -| | | | | | -| nautilus view component | | nautilus view component | | nautilus view component | -| | | | | | -+------------------------------+ +---------------------------+ +---------------------------+ - - - -* Nautilus Architecture Summary - -Nautilus is a general-purpose shell application for browsing arbitrary -content. It is implemented as `nautilus', a container application -which excercises overall control and provides chrome, and a number of -nautilus view components. These view components may use the -`libnautilus' library to ease implementation. - -There are two types of views, content views and meta-views. A nautilus -window typically has one content view, which is displayed in the main -area of the window, and several meta-views, which are displayed on the -left, typically one at a time. The meta-views should be panels that -display information about the content being displayed, or that provide -navigation aids. - -However, ultimately multiple content views will be available and may -be switched by using an option menu. - -The nautilus application has a NautilusWindow object for each window -it displays. The NautilusWindow object provides various chrome and -uses a number of NautilusView objects to communicate with view -components. The relationship between NautilusWindow and the -NautilusViews is mostly, but not completely one-way; primarily, the -window calls the view's methods and connects to its signals. - -The NautilusView object serves as a proxy for a view component. It -provides a number of methods which correspond to the methods of the -Nautilus:View IDL interface, and translates calls to these methods to -CORBA calls to the view component. It also translates incoming calls -from the view component into signal emissions for a set of signals -that reflects that Nautilus:ViewFrame IDL interface. - -The NautilusViewFrame object serves the corresponding role in the view -component. It provides methods that correspond to the -Nautilus:ViewFrame IDL interface which it translates to CORBA calls to -the app, and translates incoming CORBA calls from the app into signal -emissions which reflect the Nautilus:View IDL interface. - -Thus, whenever the application calls a NautilusView method to -communicate with the view, a CORBA message is sent, and a signal is -emitted in the view component by NautilusViewFrame. And conversely, -when the view component calls a NautilusViewFrame method to -communicate with the app, a CORBA message is sent, and a signal is -emitted by NautilusView. - - - -* Control Flow for a Location Change - -There are two possible cases. One case is when one of the views -requests a location change. The other is when the framework itself -initiates a location change. This may happen for various reasons, such -as the user typing a URI into the location bar, the user pressing the -Back or Forward buttons, or the user selecting a bookmark. - -** A view requests a location change - -For a view to initiate a location change, view-specific code in the -component calls nautilus_view_frame_request_location_change with the -appropriate arguments. This results in the "request_location_change" -signal being emitted by the corresponding NautilusView object in the -app, as described above. The NautilusWindow has connected to this -signal, so it is made aware of the request. The app may decide to -create a new window to display the new location, or to display it in -the same window. Either way, control proceeds largely as below. - - -** The framework carries out a location change - -When a NautilusWindow has determined that it should carry out a -location change or load an initial location, it calls -`nautilus_window_change_location'. This routine begins by stopping any -previous in-progress loads. Then it determines the applicable content -views and meta-views. It then enters a state machine which results in -updating each view. - -When an individual view is being updated, one of two things may -happen. First, if the same view component is still applicable but the -location is different, `nautilus_view_notify_location_change' is -called which causes the "notify_location_change" signal to be emitted -in the view. If the same view component is no longer applicable, then -a new NautilusView object is created, and the component for the proper -iid is loaded. Then `nautilus_view_notify_location_change' is called -to set it's initial location. - - -** Other component types - -Nautilus also has built-in support for viewing locations via Bonobo -subdocuments and Bonobo controls. This is implemented in the view and -transparent to the nautilus application. However, the underlying -architecture is different. - - - -* Other Communication - -The Nautilus:View and Nautilus:ViewFrame interfaces allow for other -communication as well. - -The view may request that the frame update the status message, -indicate a certain level of progress during loading, or display a -particular selection. - -The view frame may notify the view of a change in selection, tell it -to stop a load in progress, ask it to load or save its state, or ask -it to show its properties. - -Some conventions apply to the stop and progress operations. First, -`stop_location_change' should be an idempotent operation - that is, -performing it several times in a row should have the same effect as -performing it once, and it should not cause a crash. Second, the view -should send a `request_progress_change' message with a type of either -PROGRESS_DONE_OK or PROGRESS_DONE_ERROR when it is done loading, as -appropriate. This is necessary so that the stop button can be -desensitized when loading is complete. diff --git a/docs/dnd.txt b/docs/dnd.txt deleted file mode 100644 index 8abf3919e..000000000 --- a/docs/dnd.txt +++ /dev/null @@ -1,92 +0,0 @@ - Nautilus dnd code. - ------------------ - - -Nautilus dnd code is pretty compilcated, it has a lot of entry points and exit points. -Trying to clarify this now. - -You have to implement: - -If you are a source: - drag_begin - drag_end - drag_get_data - -If you are a destination: - drag_motion - drag_data_received - drag_drop - drag_leave - - - 1) Source - --------- - -if you are a source, you have to start a drag trough gtk_drag_begin. -This will call drag_begin signal in the source. -Then, when the destination calls gtk_drag_finish, drag_end will be -called in the source. - -drag_get_data will be called in the source when the destination -calls gtk_drag_get_data - -So, the source is very easy to write: it just needs to implement -those 3 signals and it should not have any memory management issue. - - - 2) Destination - -------------- - -Things get a little bit complicated. -when the dragging cursor gets in your window, you will get drag_motion -events. In nautilus, we do many things in this function: - - we start auto-scrolling if it is necessary. - - we call nautilus_*_ensure_data - - we prelight what is under the cursor if it can accept the drag. - - we try to expand what is under you if it can accept the drop (tree view) - -nautilus_*_ensure_data is vital. It calls gtk_drag_get_data to get the -data from the source. this allows the destination to store it in advance and use it -to know if what is under the cursor can accept the drag. - -Then, when the drop occurs, drag_drop is called on the destination. -drag_drop calls gtk_drag_get_data to get the data from the source to do its drop. -Then, drag_data_received is called when the data is received. -There, we can do the actual operation involved by the drop. -Also, just before the drag_drop event, a drag_leave event is triggered. - -If no drop occurs, a drag_leave occurs. - -So, drag_data_received does 2 things: it is called to get the data when we are -in motion and store it. It is also called to do the actual drop operation when -a drop happened. - -So, drag_data_received usually does 2 tests: it tests if the data was received. -If it was received, it stores it. -Then it tests if the drop occured just before. If so, it does the operation. - -This schema involves careful memory management: - 1) 2 exit points in destination. (drag_leave and drag_data_received) - 2) a lot of things are done in the callbacks so you have to take into - account all the possible code paths. - -To solve 1), we should use ONE destroy function which cleans up the drag data. -To solve 2), we have to be very careful where we call this fution from. - -This function has to clean up: - - the list of expanded nodes (tree view). - - the autoscroll code. - - the prelighting code. - It also has to set drag_info->need_to_destroy to TRUE - so that during the next drag in this widget, the - rest of the drag data is destroyed before begening the actual - new drag. - -When we receive a drag_motion, we first test for need_to_destroy and -destroy the rest of the data left from the previous drag. This code -has to destroy/reset: - - the drag data. - - the boolean vars used to store the state of the drag. - - - diff --git a/docs/key_mouse_navigation.txt b/docs/key_mouse_navigation.txt deleted file mode 100644 index 6a23c6b8c..000000000 --- a/docs/key_mouse_navigation.txt +++ /dev/null @@ -1,112 +0,0 @@ -This document describes the keyboard and mouse navigation model used -in the default Nautilus views in detail. This is useful as a a guide -for people implementing a Nautilus view or something else that wants -to have a feel that is compatible with Nautilus. - -*********** Icon view ******************** - -Keyboard: -========= - -Navigation and selection: - -When the focus is on the icon view you can move the currently selected -icon by using: - -Arrow Keys - moves one step in the direction -Tab - moves to the "next" icon in order (i.e. at the end of one row, - go to the first icon the next row) -Shift Tab - moves to the "previous" icon in order -Home - moves to the first icon -End - moves to the last icon - -In order to allow multiple selection the above navigation keys can be -combined with the Control key to move the keyboard focus without -affecting the current selection. If you use normal movement (not using -control) all the previously selected icons will be deselected. - -If several icons are selected and there is no keyboard focus you press -up or left will start navigating from the topmost leftmost icon, while -pressing down or right will start from the bottommost rightmost -icon. This works the same way if you hold down Control. - -To select or deselect an icon position the keyboard focus on it and -press ctlr-space. ctrl-space with no keyboard focus produces a -keyboard focus at the first selected icon, or the first one if none -are selected. - -In manual layout (and especially, on the desktop) the keyboard arrow -keys work in a slightly different way. To allow all icons to be -reached the closest icon in the quadrant of the direction selected -will be used as the "next" icon when navigating. - -Other keyboard shortcuts: - -Return, Keypad Return - Activate the selected objects -Space (without control) - Activate the selected objects -Escape - Undo icon stretching if in progress - -Alt Left - go back -Alt Right - go forward -Alt Up - go up a directory -Alt Down - enter directory / activate selection - -Shift-F10 bring up context menu for selection, or the directory context menu if nothing is selected -Ctrl-F10 bring up context menu for directory - -Other key presses are used for typeahead search - -In rename mode: - -Escape - Cancel rename -Return, Keypad Return - Finish rename - -Mouse: -====== - -In double click mode: - -Clicking on an icon selects it and deselects all others on -BUTTON_PRESS. Dragging does the default dnd file operation. - -Clicking on blank space deselect all selected icons. Doesn't allow -dragging. - -Double clicking (both clicks on the same icon) with no modifiers -activates the clicked file. (And deselects the others due to the first -click.) - -Clicking when Control (Shift can also be used, which is not written -out below) is held down can be used to do multiple selections. - -Control-click on empty space does nothing. -Control-click on unselected icon selects it on BUTTON_PRESS -Control-click on selected icon de-selects it on BUTTON_RELEASE -Control-double click does nothing -Control can be held down while starting a drag - -While doing a drag modifers affect the operation the drag causes: -Control - Copy the files -Shift - Move the files -Alt - Open a menu with the available alternatives - -All the basic clicks are typically done with the left button, but can -be done with the other buttons to. [Do we want this?] However some of -the buttons also have special operations: - -Right-click on a selected icon opens the context menu for the selected -icons. -Right-click on empty space opens the context menu for the directory. -Middle-button drag always opens the menu with possible operations on -drop. - -In single click mode: - -Single click mode work just like double click mode except single -clicks on icons activate the icon on button release if you didn't -drag, didn't hold down for 1.5 secs or clicked twice within the -double-click time. - -*********** List view ******************** - -[TODO: Add stuff here] diff --git a/docs/load-states.dia b/docs/load-states.dia Binary files differdeleted file mode 100644 index d650ceae1..000000000 --- a/docs/load-states.dia +++ /dev/null diff --git a/docs/nautilus-internals.pdf b/docs/nautilus-internals.pdf Binary files differdeleted file mode 100644 index 8d321f1d8..000000000 --- a/docs/nautilus-internals.pdf +++ /dev/null diff --git a/docs/nautilus-internals.sxw b/docs/nautilus-internals.sxw Binary files differdeleted file mode 100644 index e3e9f91fe..000000000 --- a/docs/nautilus-internals.sxw +++ /dev/null diff --git a/docs/nautilus-io.txt b/docs/nautilus-io.txt deleted file mode 100644 index 81dc6a059..000000000 --- a/docs/nautilus-io.txt +++ /dev/null @@ -1,255 +0,0 @@ -Nautilus I/O Primer -draft ("Better Than Nothing") -2001-08-23 -Darin Adler <darin@bentspoon.com> - -The Nautilus shell, and the file manager inside it, does a lot of -I/O. Because of this, there are some special disciplines required when -writing Nautilus code. - -No I/O on the main thread - -To be able to respond to the user quickly, Nautilus needs to be -designed so that the main user input thread does not block. The basic -approach is to never do any disk I/O on the main thread. - -In practice, Nautilus code does assume that some disk I/O is fast, in -some cases intentionally and in other cases due to programmer -sloppiness. The typical assumption is that reading files from the -user's home directory and the installed files in the Nautilus datadir -are very fast, effectively instantaneous. - -So the general approach is to allow I/O for files that have file -system paths, assuming that the access to these files is fast, and to -prohibit I/O for files that have arbitrary URIs, assuming that access -to these could be arbitrarily slow. Although this works pretty well, -it is based on an incorrect assumption, because with NFS and other -kinds of abstract file systems, there can be arbitrarily slow parts of -the file system that have file system paths. - -For historical reasons, threading in Nautilus is done through the -gnome-vfs asynchronous I/O abstraction rather than using threads -directly. This means that all the threads are created by gnome-vfs, -and Nautilus code runs on the main thread only. Thus, the rule of -thumb is that synchronous gnome-vfs operations like the ones in -<libgnomevfs/gnome-vfs-ops.h> are illegal in most Nautilus -code. Similarly, it's illegal to ask for a piece of information, say a -file size, and then wait until it arrives. The program's main thread -must be allowed to get back to the main loop and start asking for user -input again. - -How NautilusFile is used to do this - -The NautilusFile class presents an API for scheduling this -asynchronous I/O and dealing with the uncertainty of when the -information will be available. (It also does a few other things, but -that's the main service it provides.) When you want information about -a particular file or directory, you get the NautilusFile object for -that item using nautilus_file_get. This operation, like most -NautilusFile operations, is not allowed to do any disk I/O. Once you -have a NautilusFile object, you can ask it questions like "What is -your file type?" by calling functions like -nautilus_file_get_file_type. However, for a newly created NautilusFile -object the answer is almost certainly "I don't know." Each function -defines a default, which is the answer given for "I don't know." For -example, nautilus_file_get_type will return -GNOME_VFS_FILE_TYPE_UNKNOWN if it doesn't yet know the type. - -It's worth taking a side trip to discuss the nature of the -NautilusFile API. Since these classes are a private part of the -Nautilus implementation, we make no effort to have the API be -"complete" in an abstract sense. Instead we add operations as -necessary and give them the semantics that are most handy for our -purposes. For example, we could have a nautilus_file_get_size that -returns a special distinguishable value to mean "I don't know" or a -separate boolean instead of returning 0 for files where the size is -unknown. This is entirely motivated by pragmatic concerns. The intent -is that we tweak these calls as needed if the semantics aren't good -enough. - -Back to the newly created NautilusFile object. If you actually need to -get the type, you need to arrange for that information to be fetched -from the file system. There are two ways to make this request. If you -are planning to display the type on an ongoing basis then you want to -tell the NautilusFile that you'll be monitoring the file's type and want to -know about changes to it. If you just need one-time information about -the type then you'll want to be informed when the type is -discovered. The calls used for this are nautilus_file_monitor_add and -nautilus_file_call_when_ready respectively. Both of these calls take a -list of information needed about a file. If all you need is the file -type, for example, you would pass a list containing just -NAUTILUS_FILE_ATTRIBUTE_FILE_TYPE (the attributes are defined in -nautilus-file-attributes.h). Not every call has a corresponding file -attribute type. We add new ones as needed. - -If you do a nautilus_file_monitor_add, you also typically connect to -the NautilusFile object's changed signal. Each time any monitored -attribute changes, a changed signal is emitted. The caller typically -caches the value of the attribute that was last seen (for example, -what's displayed on screen) and does a quick check to see if the -attribute it cares about has changed. If you do a -nautilus_file_call_when_ready, you don't typically need to connect to -the changed signal, because your callback function will be called when -and if the requested information is ready. - -Both a monitor and a callback can be cancelled. For ease of -use, neither requires that you store an ID for -canceling. Instead, the monitor function uses an arbitrary client -pointer, which can be any kind of pointer that's known to not conflict -with other monitorers. Usually, this is a pointer to the monitoring -object, but it can also be, for example, a pointer to a global -variable. The call_when_ready function uses the callback function and callback -data to identify the particular callback to cancel. One advantage of the monitor -API is that it also lets the NautilusFile framework know that the file -should be monitored for changes made outside Nautilus. This is how we -know when to ask FAM to monitor a file or directory for us. - -Lets review a few of the concepts: - -1) Nearly all NautilusFile operations, like nautilus_file_get_type, - are not allowed to do any disk I/O. -2) To cause the actual I/O to be done, callers need to use set up - either a monitor or a callback. -3) The actual I/O is done by asynchronous gnome-vfs calls, so the work - is done on another thread. - -To work with an entire directory of files at once, you use -a NautilusDirectory object. With the NautilusDirectory object you can -monitor a whole set of NautilusFile objects at once, and you can -connect to a single "files_changed" signal that gets emitted whenever -files within the directory are modified. That way you don't have to -connect separately to each file you want to monitor. These calls are -also the mechanism for finding out which files are in a directory. In -most other respects, they are like the NautilusFile calls. - -Caching, the good and the bad - -Another feature of the NautilusFile class is the caching. If you keep -around a NautilusFile object, it keeps around information about the -last known state of that file. Thus, if you call -nautilus_file_get_type, you might well get file type of the file found -at this location the last time you looked, rather than the information -about what the file type is now, or "unknown". There are some problems -with this, though. - -The first problem is that if wrong information is cached, you need -some way to "goose" the NautilusFile object and get it to grab new -information. This is trickier than it might sound, because we don't -want to constantly distrust information we received just moments -before. To handle this, we have the -nautilus_file_invalidate_attributes and -nautilus_file_invalidate_all_attributes calls, as well as the -nautilus_directory_force_reload call. If some code in Nautilus makes a -change to a file that's known to affect the cached information, it can -call one of these to inform the NautilusFile framework. Changes that -are made through the framework itself are automatically understood, so -usually these calls aren't necessary. - -The second problem is that it's hard to predict when information will -and won't be cached. The current rule that's implemented is that no -information is cached if no one retains a reference to the -NautilusFile object. This means that someone else holding a -NautilusFile object can subtly affect the semantics of whether you -have new data or not. Calling nautilus_file_call_when_ready or -nautilus_file_monitor_add will not invalidate the cache, but rather -will return you the already cached information. - -These problems are less pronounced when FAM is in use. With FAM, any -monitored file is highly likely to have accurate information, because -changes to the file will be noticed by FAM, and that in turn will -trigger new I/O to determine what the new status of the file is. - -Operations that change the file - -You'll note that up until this point, I've only discussed getting -information about the file, not making changes to it. NautilusFile -also contains some APIs for making changes. There are two kinds of -these. - -The calls that change metadata are examples of the first kind. These -calls make changes to the internal state right away and schedule I/O -to write the changes out to the file system. There's no way to detect -if the I/O succeeds or fails, and as far as the client code is -concerned the change takes place right away. - -The calls that make other kinds of file system change are examples of -of the second kind. These calls take a -NautilusFileOperationCallback. They are all cancellable, and they give -a callback when the operation completes, whether it succeeds or fails. - -Files that move - -When a file is moved, and the NautilusFile framework knows it, then -the NautilusFile and NautilusDirectory objects follow the file rather -than staying stuck to the path. This has a direct influence on the -user interface of Nautilus -- if you move a directory, already-open -windows and property windows will follow the directory around. - -This means that keeping around a NautilusFile object and keeping -around a URI for a file have different semantics, and there are -cases where one is the better choice and cases where the other is. - -Icons - -The current implementation of the Nautilus icon factory uses -synchronous I/O to get the icons and ignores these guidelines. The -only reason this doesn't ruin the Nautilus user experience is that it -also refuses to even try to fetch icons from URIs that don't -correspond to file system paths, which for most cases means it limits -itself to reading from the high-speed local disk. Don't ask me what -the repercussions of this are for NFS; do the research and tell me -instead! - -Slowness caused by asynchronous operations - -One danger in all this asynchronous I/O is that you might end up doing -repeated drawing and updating. If you go to display a file right -after asking for information about it, you might immediately show an -"unknown file type" icon. Then, milliseconds later, you may complete -the I/O and discover more information about the file, including the -appropriate icon. So you end up drawing the icon twice. There are a -number of strategies for preventing this problem. One of them is to -allow a bit of hysteresis and wait some fixed amount of time after -requesting the I/O before displaying the "unknown" state. One -strategy that's used in Nautilus is to wait until some basic -information is available until displaying anything. This might make -the program overall be faster, but it might make it seem slower, -because you don't see things right away. [What other strategies -are used in Nautilus now for this?] - -How to make Nautilus slow - -If you add I/O to the functions in NautilusFile that are used simply -to fetch cached file information, you can make Nautilus incredibly I/O -intensive. On the other hand, the NautilusFile API does not provide a -way to do arbitrary file reads, for example. So it can be tricky to -add features to Nautilus, since you first have to educate NautilusFile -about how to do the I/O asynchronously and cache it, then request the -information and have some way to deal with the time when it's not yet -known. - -Adding new kinds of I/O usually involves working on the Nautilus I/O -state machine in nautilus-directory-async.c. If we changed Nautilus to -use threading instead of using gnome-vfs asychronous operations, I'm -pretty sure that most of the changes would be here in this -file. That's because the external API used for NautilusFile wouldn't -really have a reason to change. In either case, you'd want to schedule -work to be done, and get called back when the work is complete. - -[We probably need more about nautilus-directory-async.c here.] - -Future direction - -Some have suggested that by using threading directly in Nautilus -rather than using it indirectly through the gnome-vfs async. calls, -we could simplify the I/O code in Nautilus. It's possible this would -make a big improvement, but it's also possible that this would primarily -affect the internals and implementation details of NautilusFile and -still leave the rest of the Nautilus code the same. - -That's all for now - -This is a very rough early draft of this document. Let me know about -other topics that would be useful to be covered in here. - - -- Darin diff --git a/docs/nautilus.faq b/docs/nautilus.faq deleted file mode 100644 index 1514efd02..000000000 --- a/docs/nautilus.faq +++ /dev/null @@ -1,7 +0,0 @@ -1. What is Nautilus ? - - Nautilus is an open-source file manager and graphical shell being - developed by Eazel, Inc. and others. It is part of the GNOME project, and its - source code can be found in the GNOME CVS repository. Nautilus is still in - the early stages of development. It will become an integral part of the - GNOME desktop environment when it is finished. diff --git a/docs/recommended-books.html b/docs/recommended-books.html deleted file mode 100644 index f8e893b58..000000000 --- a/docs/recommended-books.html +++ /dev/null @@ -1,167 +0,0 @@ -<html> - -<head> -<title>Eazel: Darin's Recommended Programming Books</title> -</head> - -<body> - -<p>This document was really more for Eazel than for all Nautilus hackers, -but since the style guide references it, I checked it into the Nautilus CVS -for now. Later we can figure out what to do with it.</p> - -<p>This document is left over from when Eazel was doing a program in C++. -Soon, I'll rearrange the document so it doesn't put all the C++ stuff first, -since C++ is immaterial for the current Nautilus project.</p> - -<p>If you buy books from Amazon.com using the links on this page, Darin will get a small kickback from Amazon.</p> - -<p>One of the main reasons for creating this list is that there are many poor C++ books out there. -I've picked out a small number of extremely useful books so you won't have to wade through the weaker ones.</p> - -<h2>C++ Reference Books</h2> - -<p>These books cover the C++ language and library. All of them except for the -C++ standard itself also contain useful introductory material. For some -programmers, these are enough to explain the features of the language.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201889544/dianepattersonstA"><b><i>The C++ Programming Language, Third Edition</i></b></a>, -Bjarne Stroustrup. This is the book by the creator of the C++ language. This third edition is far superior -to the first two, and covers the ISO Standard version of the language in detail, including the library. -Any serious C++ programmer should read this book. There have been many corrections since the first printing, so get -the newest printing you can. Bjarne has <a href="http://www.research.att.com/~bs/3rd.html">supporting materials</a> -for the book on the web, including the errata lists that enumerate all changes between printings.</p> - -<p><a name="Josuttis" href="http://www.amazon.com/exec/obidos/ASIN/0201379260/dianepattersonstA"><b><i>The C++ Standard Library</i></b></a>, -Nicolai M. Josuttis. This book has the best coverage of the library. There have been tons of others that cover -the library, or focus on the STL or streams. But Josuttis covers all these subjects better than any of his -predecessors. Since we use the library extensively in Eazel projects, this is a must read. -The author has some useful <a href="http://josuttis.com/libbook">supporting materials</a> on the web.</p> - -<h2>C++ Technique Books</h2> - -<p>These books are about specific programming techniques for writing code in C++. -They can help you understand idioms you'll find in our code. -This kind of idiomatic programming is important in C++, because the language -gives you so much freedom to write unusable, unmaintainable code.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201615622/dianepattersonstA"><b><i>Exceptional C++</i></b></a>, -Herb Sutter. This is a collection of material that was originally part of Herb's -<a href="http://www.peerdirect.com/resources"><i>Guru of the Week</i></a>. This includes much of the most -advanced C++ information available. I learned many of the most important techniques from Herb, including -the swap technique for writing safe assignment operators. Herb covers each topic thoroughly.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201423391/dianepattersonstA"><b><i>Ruminations on C++</i></b></a>, -Andrew Koenig and Barbara Moo.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201924889/dianepattersonstA"><b><i>Effective C++, Second Edition</i></b></a> -and <a href="http://www.amazon.com/exec/obidos/ASIN/020163371X/dianepattersonstA"><b><i>More Effective C++</i></b></a>, -Scott Meyers. These books contain a laundry list of important C++ idioms. The books are a bit less -important now than when they were first released, but still full of valuable stuff. There's also a -<a href="http://www.amazon.com/exec/obidos/ASIN/0201310155/dianepattersonstA">CD edition</a> -(there's a <a href="http://mox.eazel.com/mec">copy</a> of it on Rob's machine) -that contains both books in electronic form. The publisher's web site has a good collection of -supporting materials for both -<a href="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-92488-9">the original</a> and -<a href="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-63371-X">the second book</a></p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201543303/dianepattersonstA"><b><i>The Design and Evolution of C++</i></b></a>, -Bjarne Stroustrup. While this book doesn't prescribe any specific techniques, it will help you understand the -tradeoffs behind all the language features, and how C++ got to be what it is. I highly recommend it.</p> - -<h2>C++ Tutorial Books</h2> - -<p>These books explain C++ programming from scratch. These particular examples are so good that they -can be useful even for experienced programmers who already know C++ well.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201485184/dianepattersonstA"><b><i>Essential C++</i></b></a>, -Stanley Lippman. This tutorial is much more useful than the longer and more complete works, like -<a href="#Primer"><i>C++ Primer</i></a>. -It covers the features and the reasons for the features quite well. In particular, it has a good explanation -of references and pointers and why you'd use one or the other. It covers templates and exceptions fairly well.</p> - -<h2>Gtk Books</h2> - -<p>OK, so I'm not an expert on Gtk yet. But I'm becoming one.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0735700788/dianepattersonstA"><b><i>Gtk+/Gnome Application Development</i></b></a>, -Havoc Pennington. I learned a lot from this book. But it's all Gtk+ and C; things are done -a bit differently with Gtk-- from C++. It's still worth reading.</p> - -<h2>Programming Technique Books</h2> - -<p>These books are valuable because of the ideas in them, but are not specific to a particular programming language or toolkit.</p> - -<p><a name="Refactoring" href="http://www.amazon.com/exec/obidos/ASIN/0201485672/dianepattersonstA"><b><i>Refactoring</i></b></a>, -Martin Fowler. This book outlines a philosophy of programming that we embrace at Eazel. The ideas -about changing existing code to improve it so it can be modified are extremely important. The ideas -about unit testing as a means to this end shape the way we use unit testing at Eazel. -All the examples in the book are in Java, but the ideas apply well to C++.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/020161586X/dianepattersonstA"><b><i>The Practice of Programming</i></b></a>, -Brian Kernighan, Rob Pike. This book, by two of the most famous UNIX programmers, covers a lot of basic -programming smarts. I don't agree with everything they have to say, but the book is great as a whole.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201657880/dianepattersonstA"><b><i>Programming Pearls, Second Edition</i></b></a>, -Jon Bentley. This classic has recently been updated with a second edition. I haven't read the second edition -yet, but I'm sure it's great. When I read it, I'll put more specific comments here.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201633612/dianepattersonstA"><b><i>Design Patterns</i></b></a>. -There's also a <a href="http://www.amazon.com/exec/obidos/ASIN/0201634988/dianepattersonstA">CD edition</a> -(there's a <a href="http://mox.eazel.com/dp">copy</a> of it on Rob's machine).</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201350882/dianepattersonstA"><b><i>Algorithms in C++, Third Edition</i></b></a>, -Robert Sedgewick. The <a href="http://www.amazon.com/exec/obidos/ASIN/0201314525/dianepattersonstA">original version</a> is in C. -There's also an upcoming <a href="http://www.amazon.com/exec/obidos/ASIN/0201361205/dianepattersonstA">Java version</a>.</p> - -<h2>Books I Have Read, But Do Not Recommend</h2> - -<p>I've also read many books on these topics that were less useful than the ones listed above. -Here are a few that were not as exemplary. I won't try to sort out the ones that I found simply "not as useful as the best ones" -from the truly awful. If you see a book that's not on this list, it might be one I'd recommend. Maybe -I haven't read it.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201498413/dianepattersonstA"><b><i>C Interfaces and Implementations</i></b></a>.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201596415/dianepattersonstA"><b><i>C++ IOStreams Handbook</i></b></a>, -Steve Teale. <a href="Josuttis">Josuttis</a> covers streams better.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201616416/dianepattersonstA"><b><i>Extreme Programming Explained</i></b></a>. -My love for <a href="Refactoring"><i>Refactoring</i></a> had me excited about this one, but it was a disappointment.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201309564/dianepattersonstA"><b><i>Generic Programming and the STL</i></b></a>, -Matt Austern. I don't know of anyone who knows more about the STL than Matt Austern, who's currently -maintaining the main implementation at SGI. But <a href="Josuttis">Josuttis</a> covers the STL better.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0131209655/dianepattersonstA"><b><i>Industrial Strength C++</i></b></a>.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201834545/dianepattersonstA"><b><i>Inside the C++ Object Model</i></b></a>.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201633620/dianepattersonstA"><b><i>Large-Scale C++ Software Design</i></b></a>, -John Lakos.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0130142697/dianepattersonstA"><b><i>Objects Unencapsulated: Java, Eiffel and C++??</i></b></a>. -This is a basically an "Eiffel is great, C++ sucks" book. Some interesting insights, but a lot of sloppy thinking.</p> - -<h2>Books That Need Review</h2> - -<p>This is a list of possibly important books that I haven't checked out yet.</p> - -<p><a name="Primer" href="http://www.amazon.com/exec/obidos/ASIN/0201824701/dianepattersonstA"><b><i>C++ Primer, Third Edition</i></b></a>, -Stanley Lippman, Josee Lajoie. The earlier editions were good but not great. But I have reason -to believe that this one might be better than those were.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201309939/dianepattersonstA"><b><i>C++ Primer Answer Book</i></b></a>. -I checked, and this answer book does go with the third edition of <i>C++ Primer</i>.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0201309599/dianepattersonstA"><b><i>Design Patterns and Contracts</i></b></a>.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0735700214/dianepattersonstA"><b><i>Developing Linux Applications with GTK+ and GDK</i></b></a>.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0764546406/dianepattersonstA"><b><i>Linux Gnome/Gtk Programming Bible</i></b></a>.</p> - -<p><a href="http://www.amazon.com/exec/obidos/ASIN/0672318296/dianepattersonstA"><b><i>Sams Teach Yourself Gtk+ Programming in 21 Days</i></b></a>.</p> - -</body> - -</html> diff --git a/docs/smoketests.html b/docs/smoketests.html deleted file mode 100644 index 4f43936a5..000000000 --- a/docs/smoketests.html +++ /dev/null @@ -1,555 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> -<HTML> -<HEAD> - <TITLE></TITLE> - <META NAME="GENERATOR" CONTENT="StarOffice/5.1 (Linux)"> - <META NAME="AUTHOR" CONTENT=" "> - <META NAME="CREATED" CONTENT="20000901;18303000"> - <META NAME="CHANGEDBY" CONTENT="Josh Barrow"> - <META NAME="CHANGED" CONTENT="20010216;14060700"> - <META HTTP-EQUIV="content-type" CONTENT="text/html;charset=iso-8859-1"> - <STYLE> - <!-- - A:link { color: #009999 } - --> - </STYLE> -</HEAD> -<BODY LINK="#009999" BGCOLOR="#ffffff"> -<P ALIGN=LEFT><FONT COLOR="#004252"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><FONT SIZE=6><B>Nautilus -Smoke Tests</B></FONT></FONT></FONT></P> -<P ALIGN=LEFT STYLE="font-weight: medium"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><FONT SIZE=4>The -Nautilus Smoke Tests are a minimal set of tests, to determine whether -a build is usable for testing, and to catch obvious regressions.</FONT></FONT></P> -<P ALIGN=LEFT><BR><BR> -</P> -<P ALIGN=LEFT><FONT COLOR="#004252"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><FONT SIZE=3><B>Views</B></FONT></FONT></FONT></P> -<P ALIGN=LEFT><FONT SIZE=3><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Before -beginning this section, open a folder which contains at least one -MP3, image (GIF, JPEG or PNG), plain text, HTML, PDF, and RPM file.<B> -(For those inside the Eazel firewall, these are in -/h/public/QE/smoketests.)</B><BR><BR>Also be sure to be in -single-click mode. (Preferences | Click Behavior | 'Active items with -single click')<BR></FONT></FONT><BR><BR> -</P> -<TABLE WIDTH=100% BORDER=1 CELLPADDING=4 CELLSPACING=3> - <COL WIDTH=25*> - <COL WIDTH=60*> - <COL WIDTH=83*> - <COL WIDTH=87*> - <THEAD> - <TR VALIGN=TOP> - <TH WIDTH=10% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test - #</SPAN></FONT></P> - </TH> - <TH WIDTH=24% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test</SPAN></FONT></P> - </TH> - <TH WIDTH=33% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test - Steps</SPAN></FONT></P> - </TH> - <TH WIDTH=34% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Expected - Results</SPAN></FONT></P> - </TH> - </TR> - </THEAD> - <TBODY> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-1</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as Icon</FONT></P> - </TD> - <TD WIDTH=33%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Select "View as Icons" from pop-up menu.</FONT> - </P> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - Zoom in to 400% and out to 25%, both via the pop-up menu, and via - +/- icons.</FONT></P> - <P><BR> - </P> - </TD> - <TD WIDTH=34%> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-2</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as List</FONT></P> - </TD> - <TD WIDTH=33% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Select "View as List" from pop-up menu</FONT> - </P> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - Zoom in to 400% and out to 25%, and via +/- icons.</FONT></P> - </TD> - <TD WIDTH=34% BGCOLOR="#ffffcc"> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-3</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as Music</FONT></P> - </TD> - <TD WIDTH=33%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Select "View as Music" from pop-up menu.</FONT> - </P> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - Play an MP3.</FONT></P> - </TD> - <TD WIDTH=34%> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-4</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as Web Page</FONT></P> - </TD> - <TD WIDTH=33% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on a file of type "HTML Document".</FONT></P> - </TD> - <TD WIDTH=34% BGCOLOR="#ffffcc"> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-5</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as Text</FONT></P> - </TD> - <TD WIDTH=33%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on a file of type "plain text".</FONT></P> - </TD> - <TD WIDTH=34%> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-6</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as Image</FONT></P> - </TD> - <TD WIDTH=33% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on an image of type "JPEG image", "GIF - image", or "PNG image". (confirm)</FONT></P> - </TD> - <TD WIDTH=34% BGCOLOR="#ffffcc"> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-7</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as Hardware</FONT></P> - </TD> - <TD WIDTH=33%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Type "hardware:" or "hardware:overview" into - the Location bar.</FONT></P> - </TD> - <TD WIDTH=34%> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-8</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as PDF Document</FONT></P> - </TD> - <TD WIDTH=33% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on a PDF file.</FONT></P> - </TD> - <TD WIDTH=34% BGCOLOR="#ffffcc"> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">V-9</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">View - as Package</FONT></P> - </TD> - <TD WIDTH=33%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on any Red Hat Package Manager file.</FONT></P> - </TD> - <TD WIDTH=34%> - <P><BR> - </P> - </TD> - </TR> - </TBODY> -</TABLE> -<P ALIGN=LEFT><BR><BR> -</P> -<P ALIGN=LEFT><FONT COLOR="#004252"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><FONT SIZE=3><B>File -Operations</B></FONT></FONT></FONT></P> -<P ALIGN=LEFT STYLE="font-weight: medium"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><FONT SIZE=3>Before -beginning this section, change your Click Behavior (in Preferences) -to 'Active items with a double click'.</FONT></FONT></P> -<TABLE WIDTH=100% BORDER=1 CELLPADDING=4 CELLSPACING=3> - <COL WIDTH=25*> - <COL WIDTH=60*> - <COL WIDTH=106*> - <COL WIDTH=64*> - <THEAD> - <TR VALIGN=TOP> - <TH WIDTH=10% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test - Number</SPAN></FONT></P> - </TH> - <TH WIDTH=24% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test</SPAN></FONT></P> - </TH> - <TH WIDTH=42% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test - Steps</SPAN></FONT></P> - </TH> - <TH WIDTH=25% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Expected - Results</SPAN></FONT></P> - </TH> - </TR> - </THEAD> - <TBODY> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">F-1</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Rename - a file or folder</FONT></P> - </TD> - <TD WIDTH=42%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on a file, and choose "Rename" from the File or - context menu.</FONT> - </P> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - Type in a new name</FONT></P> - </TD> - <TD WIDTH=25%> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">F-2</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Duplicate - a file or folder</FONT></P> - </TD> - <TD WIDTH=42% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on a file, and choose "Duplicate" from the File - or context menu.</FONT></P> - </TD> - <TD WIDTH=25% BGCOLOR="#ffffcc"> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">F-3</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Create - a link to a file or folder</FONT></P> - </TD> - <TD WIDTH=42%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on a file, and choose "Create Link" from the File - or context menu.</FONT></P> - </TD> - <TD WIDTH=25%> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">F-4</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Stretch - an icon</FONT></P> - </TD> - <TD WIDTH=42% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Click on a file, and choose "Stretch Icon" from the - File or context menu.</FONT> - </P> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - Drag the icon by a corner, and enlarge or shrink it.</FONT></P> - </TD> - <TD WIDTH=25% BGCOLOR="#ffffcc"> - <P><BR> - </P> - </TD> - </TR> - </TBODY> -</TABLE> -<P ALIGN=LEFT><BR><BR> -</P> -<P ALIGN=LEFT><B><FONT SIZE=3><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><FONT COLOR="#004252">Desktop -Operations</FONT></FONT></FONT></B></P> -<TABLE WIDTH=100% BORDER=1 CELLPADDING=4 CELLSPACING=3> - <COL WIDTH=26*> - <COL WIDTH=61*> - <COL WIDTH=106*> - <COL WIDTH=64*> - <THEAD> - <TR VALIGN=TOP> - <TH WIDTH=10% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test - Number</SPAN></FONT></P> - </TH> - <TH WIDTH=24% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test</SPAN></FONT></P> - </TH> - <TH WIDTH=41% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test - Steps</SPAN></FONT></P> - </TH> - <TH WIDTH=25% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Expected - Results</SPAN></FONT></P> - </TH> - </TR> - </THEAD> - <TBODY> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">D-1</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Empty - Trash</FONT></P> - </TD> - <TD WIDTH=41%> - <P STYLE="font-style: normal"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Drag files or folders onto the Trash icon.</FONT></P> - <P STYLE="font-style: normal"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - Right-click on the Trash, and select "Empty Trash" - (alternatively, double-click on the trash can, and select "Empty - Trash" from the File menu.)</FONT></P> - <P STYLE="font-style: normal"><BR> - </P> - </TD> - <TD WIDTH=25%> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">D-2</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Drag - file to Desktop</FONT></P> - </TD> - <TD WIDTH=41% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Drag a file from a Nautilus view window to the Desktop</FONT></P> - </TD> - <TD WIDTH=25% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">File - should be moved to desktop.</FONT></P> - </TD> - </TR> - </TBODY> -</TABLE> -<P ALIGN=LEFT STYLE="font-weight: medium"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><BR><BR><B><FONT SIZE=3><FONT COLOR="#004252">Preferences/Customization</FONT></FONT></B></FONT></P> -<TABLE WIDTH=100% BORDER=1 CELLPADDING=4 CELLSPACING=3> - <COL WIDTH=26*> - <COL WIDTH=61*> - <COL WIDTH=57*> - <COL WIDTH=112*> - <THEAD> - <TR VALIGN=TOP> - <TH WIDTH=10% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test - Number</SPAN></FONT></P> - </TH> - <TH WIDTH=24% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test</SPAN></FONT></P> - </TH> - <TH WIDTH=22% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Test - Steps</SPAN></FONT></P> - </TH> - <TH WIDTH=44% BGCOLOR="#ffce39"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular"><SPAN STYLE="background: transparent">Expected - Results</SPAN></FONT></P> - </TH> - </TR> - </THEAD> - <TBODY> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">P-1</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Switch - Themes</FONT></P> - </TD> - <TD WIDTH=22%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - From a Nautilus window, choose "Nautilus Themes" from - the Edit menu.</FONT> - </P> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - Try each of the themes.</FONT></P> - </TD> - <TD WIDTH=44%> - <P><BR> - </P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">P-2</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Switch - User Mode</FONT></P> - </TD> - <TD WIDTH=22% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - From a Nautilus window, try each of the three user modes.</FONT></P> - </TD> - <TD WIDTH=44% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">In - Beginner mode:</FONT> - </P> - <OL> - <LI><P STYLE="margin-bottom: 0in"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">The - user mode menu's "Edit Beginner User Level" should - lead to a dialog with very minimal settings.</FONT></P> - <LI><P STYLE="margin-bottom: 0in"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Dot - files (e.g. .bashrc) should not be displayed.</FONT> - </P> - <LI><P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">The - "Special Flags" portion of the Show Properties - dialog's "Permissions" pane should be omitted.</FONT> - </P> - </OL> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">In - Intermediate mode:</FONT></P> - <OL> - <LI><P STYLE="margin-bottom: 0in"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Dot - files (e.g. .bashrc) should not be displayed.</FONT> - </P> - <LI><P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">The - "Special Flags" portion of the Show Properties - dialog's "Permissions" pane should be omitted.</FONT> - </P> - </OL> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">In - Expert mode, none of the above user experience simplification - should occur.</FONT></P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">P-3</FONT></P> - </TD> - <TD WIDTH=24%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Switch - Anti-aliasing mode</FONT></P> - </TD> - <TD WIDTH=22%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - While in Intermediate or Expert mode, choose "Preferences..." - From the user mode menu.</FONT> - </P> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - In the "Appearance" category, deselect the "Use - smoother (but slower) graphics" checkbox.</FONT></P> - </TD> - <TD WIDTH=44%> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Text - and icons should no longer be anti-aliased.</FONT></P> - </TD> - </TR> - <TR VALIGN=TOP> - <TD WIDTH=10% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">P-4</FONT></P> - </TD> - <TD WIDTH=24% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Change - Background</FONT></P> - </TD> - <TD WIDTH=22% BGCOLOR="#ffffcc"> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">1. - Choose "Backgrounds and Emblems" from the Edit menu.</FONT> - </P> - <P><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">2. - Drag a few colors and backgrounds to the sidebar & main - window pane.</FONT></P> - </TD> - <TD WIDTH=44% BGCOLOR="#ffffcc"> - <P><BR> - </P> - </TD> - </TR> - </TBODY> -</TABLE> -<P ALIGN=LEFT><BR><BR> -</P> -<P ALIGN=RIGHT STYLE="margin-bottom: 0in"><FONT SIZE=2 STYLE="font-size: 9pt"><FONT FACE="Arial, Helvetica, Geneva, Swiss, SunSans-Regular">Maintained -by <A HREF="mailto:josh@eazel.com">Josh Barrow</A> for Nautilus -Quality Engineering, originally written by <A HREF="mailto:eli@eazel.com">Eli -Goldberg</A>; feedback welcome.<BR>Adaptation and reuse for other -open source projects is freely permitted.<BR>Last Updated: 9/28/2000</FONT></FONT></P> -</BODY> -</HTML>
\ No newline at end of file diff --git a/docs/state-machines.txt b/docs/state-machines.txt deleted file mode 100644 index a762aa9dc..000000000 --- a/docs/state-machines.txt +++ /dev/null @@ -1,77 +0,0 @@ - -Proposal for the loading state machines - - -ViewFrame state machine - -States are: - - -E: Empty (the initial state right after construction) -A: Activating (waiting for component to be activated) -N: No load_location request (a view component has been loaded, but no load_location request has been sent yet) -W: Waiting (waiting for a response after a load request) -U: Underway (the component has responded and the load is assumed underway) -L: Loaded (the component has finished loading successfully) -F: Failed (there was a fatal error somewhere) - -X: this stimulus is guaranteed impossible in this state - - -Things I was unsure about: - -?2: Once a load has failed at some stage, should it be OK for Nautilus -to try to make further calls of any kind? - -Missing: - -1) "Component stops responding" stimulus. -2) Distinction of failure loading vs. crash of the component. - -Note: - -A "*" means that this is illegal but non-fatal, so we want to use g_warning. - - - State Transition Chart - - - Initial State - - | E | A | N | W | U | L | F | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - successful load_client call | A | X | X | X | X | X | ?2 | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - unsuccessful load_client call | F | X | X | X | X | X | ?2 | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - successful activated_component call | X | N | X | X | X | X | ?2 | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - unsuccessful activated_component call | X | F | X | X | X | X | ?2 | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - stop activation | E | E | X | X | X | X | ?2 | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - nautilus_view_frame_load_location call | X | F | W | W | W | W | ?2 | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - open_location call from component | X | X | N* | U | U | L | X | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - open_location_in_new_window | X | X | N* | U | U | L | X | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - report_location_change | X | X | N* | U | U | U | X | -S ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| -t report_selection_change | X | X | N* | U | U | L | X | -i ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| -m report_status | X | X | N* | U | U | L | X | -u ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| -l report_load_underway | X | X | N* | U | U | U | X | -u ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| -s report_load_progress | X | X | N* | U | U | U | X | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - report_load_complete | X | X | N* | L | L | L | X | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - report_load_failed | X | X | N* | F | F | F | X | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - set_title | X | X | N* | U | U | L | X | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - user hits cancel on timer dialog | X | X | X | F | X | X | X | - ----------------------------------------|-----|-----|-----|-----|-----|-----|-----| - diff --git a/docs/style-guide.html b/docs/style-guide.html deleted file mode 100644 index 7126a22e2..000000000 --- a/docs/style-guide.html +++ /dev/null @@ -1,137 +0,0 @@ -<html> - -<head> -<title>Nautilus Coding Style Guide</title> -</head> - -<body> - -<p>To make code written for Nautilus look and act in a predictable way, -we follow a set of guidelines that specify some details of how we write code. -To start, we follow all the guidelines outlined in the -<a href="http://developer.gnome.org/doc/guides/programming-guidelines/">GNOME Programming Guidelines</a>.</p> - -<p>This document covers both things that are not mentioned in the GNOME -Programming Guidelines and things that are mentioned there but need -to be re-emphasized because people don't follow them often enough.</p> - -<p>I'm just getting started on this document. Feedback is welcome. -Eventually I'd like better organization and tons of examples.</p> - -<blockquote> -<p>- <a href="mailto:darin@bentspoon.com">Darin</a></p> -</blockquote> - -<hr> - -<p><b>We use the most-recommended coding style from the GNOME Programming -Guidelines.</b> This means that we use the Linux kernel brace style with -8-character tabs (not the GNU brace style), we put spaces before -the parentheses that introduce function argument lists, we put the -braces that open the block for an if statement on the same line as the -if statement (part of Linux kernel brace style).</p> - -<p><b>We prefer to use words rather than acronyms or abbreviations.</b> This means that -we name classes with a prefix like Nautilus, not Ntl, for example. And we use variables -named result rather than retval or rv.</p> - -<p><b>We strive to have a minimum number of local variables.</b> This makes it -easier to move pieces of code around. For more on this, read -<a href="recommended-books.html#Refactoring"><i>Refactoring</i></a>.</p> - -<p><b>We use type casts as little as possible.</b> There are many places in GTK programming -where you have to cast to make the program work, but we do whatever we can -to avoid this. Also, we prefer to cast data pointers, rather than casting -function pointers, since there's so much more to get wrong with function -pointer casts.</p> - -<p><b>We use typedefs from <glib.h> for things like guint, guchar and gpointer, -but not gint, gchar, or gdouble.</b> Using these gives a false sense -of portability. In all three cases, using system calls like printf requires -knowing that these are the "real" int, char, and double, so there's no reason -to use a typedef that's non-standard unless it's a shorter name or clearer -in some way.</p> - -<p><b>We avoid in-band signaling.</b> This means that we avoid using special -values to indicate errors, for example. This can lead to subtle bugs when a valid -result is misinterpreted as an error, and can make it hard to tell if the code -handles errors or not.</p> - -<p><b>We code for clarity first.</b> Other concerns like efficiency are secondary. -Sometimes they become more important than clarity, but only once they are proven -to be a problem.</p> - -<p><b>We use for loops when they make the code easier to read.</b> The alternative -is usually to use a while loop. It's true that -"easy to read" is a subjective thing.</p> - -<p><b>We declare local variables at the beginning of a block.</b> C99 allows you -to declare variables anywhere in a function, but a lot of compilers still do not -support C99.</p> - -<p><b>We do not initialize local variables in their declarations.</b> C allows you -to initialize a local variable when declaring it. But no other code can run before -this, because the other statements in a function must be after all the declarations. -If there are lines of code initializing the variables in the declarations, it can -be harder to change the function around, since code must move down from the declaration -if other code needs to run after it. To avoid this, we just don't use the ability -to initialize the variable when it's declared.</p> - -<p><b>We always use braces, even for one-statement "blocks".</b> Our consensus is -to do things like this:</p> - -<blockquote> -<pre> -if (list != NULL) { - g_warning ("the list isn't empty"); -} -</pre> -</blockquote> - -<p>Instead of this:</p> - -<blockquote> -<pre> -if (list != NULL) - g_warning ("the list isn't empty"); -</pre> -</blockquote> - -<p>This applies to all control structures: if, while, for, do.</p> - -<p><b>We make each header "stand alone".</b> Our concept with C header files is -that each one must be written so it can be included without including another file -first. To test that the header files we develop have this property, we always -include the corresponding header file first in each C source file. The only exception -is the include of <config.h>, which goes first. Here's an example:</p> - -<blockquote> -<pre> -/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- - * - * nautilus-icon-factory.c: Class for obtaining icons for files and other objects. - * - * Copyright (C) 1999, 2000 Red Hat Inc. - * Copyright (C) 1999, 2000 Eazel, Inc. - * - * <i>License agreement goes here.</i> - * - * Author: John Sullivan <sullivan@eazel.com> - */ - -#include <config.h> -#include "nautilus-icon-factory.h" - -#include <string.h> -#include <stdio.h> -<i>Include statements for other header files go here.</i> - -<i>Other declarations and code go here.</i> -</pre> -</blockquote> - -<hr> - -</body> - -</html> |